CI/CD Integration

rafter ci init is coming soon. This command will auto-generate CI config for GitHub Actions, GitLab CI, and CircleCI. Until it ships, use the manual workflows below.

A single commit. One missed vulnerability. $50,000 in damages. This isn’t a hypothetical scenario—it’s happening to development teams every week. The problem isn’t that developers are careless. It’s that security scanning is still manual, optional, and easy to skip when deadlines loom. Manual security scanning creates gaps. Automated scanning catches vulnerabilities before they reach production, protecting your users and your reputation.

Two CI Modes

Rafter supports two scanning approaches in CI. Choose based on whether you have a Rafter API key.

Mode 1: Local Scan (no API key required)

Uses rafter scan local to run pattern matching and Gitleaks secret detection directly on the runner. Zero config—installs the CLI, scans, fails CI if secrets are found.

Note: rafter agent scan still works but is deprecated — it will be removed in a future major version.

- name: Rafter secret scan
  run: |
    npm install -g @rafter-security/cli
    rafter scan local . --json --quiet

Exit code 1 fails the pipeline automatically if secrets are detected. No account or API key needed. When to use: Open-source projects, teams without a Rafter subscription, or any repo where fast secret scanning at commit time is enough.

Mode 2: Backend Scan (API key required)

Uses rafter scan to trigger a full SAST analysis via the Rafter backend API (rafter.so/api/static/scan). More comprehensive—covers a wider range of vulnerability classes beyond secrets. When to use: Teams with a Rafter subscription who want full SAST coverage on every push. See Step 3 below for the complete backend scan workflow.

Introduction

Automated security scanning transforms security from an afterthought into a seamless part of your development workflow. Instead of remembering to run scans manually (and inevitably forgetting), your CI/CD pipeline automatically checks every commit and pull request for vulnerabilities. This guide shows you two approaches:

Manual setup: Step-by-step instructions for hands-on configuration
AI-assisted setup: Copy-paste workflows with AI prompts for rapid deployment

I’d recommend skimming the manual setup first so you understand what’s happening, then using the AI-assisted setup for a quick and easy setup. Plus, you’ll learn how API keys work, why they’re secure, and how to protect them properly in your CI/CD environment. If you’re not familiar with GitHub Actions, you can learn more about them here.

Why Automated Security Scanning Matters

The Manual Scanning Problem

Manual security scanning has three critical flaws:

Human Error: Developers forget to run scans, especially under pressure
Inconsistent Coverage: Different team members use different tools or settings
Late Detection: Vulnerabilities are found after code reaches production

The Automated Solution

Automated scanning eliminates these problems by:

Running on every push: No forgotten scans
Consistent configuration: Same rules applied every time
Early detection: Vulnerabilities caught before deployment
Build failure: Critical issues block deployment automatically

Understanding API Keys in CI/CD

What Are API Keys?

API keys are authentication tokens that allow automated tools to access services on your behalf. Think of them as digital keys that unlock specific capabilities—in this case, security scanning services like Rafter.

Why API Keys Are Secure

API keys are designed for programmatic access and include several security features:

Scoped permissions: Keys can only access specific services
Usage tracking: All API calls are logged and monitored
Easy rotation: Keys can be regenerated instantly if compromised
Environment isolation: Keys are stored separately from your code

How GitHub Secrets Protect Your Keys

GitHub Secrets provide enterprise-grade security for sensitive data:

Encryption at rest: Keys are encrypted when stored
Encryption in transit: Keys are encrypted when accessed
Access control: Only authorized workflows can use secrets
Audit logging: All secret access is logged

Manual Setup: Step-by-Step Configuration

Step 1: Choose Your Mode

Refer to Two CI Modes above. If you’re using local scan, skip to Step 3 and use the local scan workflow. If you’re using backend scan, continue with Step 2 to get your API key.

Step 2: Get Your Rafter API Key

(Backend scan only — skip if using local scan.) If you have an existing key saved to a safe place, copy it. Otherwise, generate a new key… Rafter protects your API keys by not storing them. You get access once, when you generate/refresh the key. Then, refreshing the key invalidates the previous key to keep it safe. It’s a way to help you rotate keys, which is best practice. Navigate to Account Settings

Go to your Rafter account settings
Look for the “API Keys” section

Generate or Retrieve Key

Click “Generate New API Key” or “Refresh API Key”
The key is automatically copied to your clipboard (it won’t be shown/copiable again)

API keys are sensitive credentials. Never commit them to your repository or share them in plain text.

Add API Key to GitHub Secrets

Navigate to your GitHub repository
Click “Settings” → “Secrets and variables” → “Actions”
Click “New repository secret”
Name: RAFTER_API_KEY
Value: Paste your API key
Click “Add secret”

Step 3: Create GitHub Workflow

Create Workflow Directory

mkdir -p .github/workflows

Option A — Local Scan Workflow (no API key) Create .github/workflows/security-scan.yml:

# .github/workflows/security-scan.yml
# No API key required. Runs pattern + Gitleaks secret scanning on the runner.

name: Rafter Secret Scan

on:
  push:
    branches: [ main ]
  pull_request:

permissions:
  contents: read

jobs:
  secret-scan:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Rafter secret scan
        run: |
          npm install -g @rafter-security/cli
          rafter scan local . --json --quiet

Exit code 1 fails the job automatically if secrets are detected. Option B — Backend Scan Workflow (API key required) Create .github/workflows/security-scan.yml:

# .github/workflows/security-scan.yml
#
# Prerequisites:
#   Add your Rafter API key as a GitHub repository secret:
#   Settings -> Secrets and variables -> Actions -> New repository secret
#   Name: RAFTER_API_KEY

name: Security Scan with Rafter

on:
  push:
    branches: [ main ]

# Least-privilege permissions (security best practice)
permissions:
  contents: read      # Checkout code
  actions: write      # Upload artifacts

jobs:
  security-scan-three:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Run security scan
        env:
          RAFTER_API_KEY: ${{ secrets.RAFTER_API_KEY }}
        run: |
            set -euo pipefail

            # 1. Trigger scan
            SCAN_ID=$(curl -fsS -X POST \
              -H "Content-Type: application/json" \
              -H "x-api-key: ${RAFTER_API_KEY}" \
              -d '{
                "repository_name": "${{ github.repository }}",
                "branch_name": "${{ github.ref_name }}",
                "scan_mode": "fast"
              }' \
              https://rafter.so/api/static/scan | jq -r '.scan_id')

            echo "SCAN_ID: $SCAN_ID"

            # 2. Wait for completion (polling), for a maximum of 10 minutes (60 loops × 10s = 600s = 10m)
            MAX_POLLS=60
            POLL_COUNT=0
            while [ $POLL_COUNT -lt $MAX_POLLS ]; do
              STATUS=$(curl -fsS -H "x-api-key: ${RAFTER_API_KEY}" \
                "https://rafter.so/api/static/scan?scan_id=$SCAN_ID" | jq -r '.status')

              if [ "$STATUS" = "completed" ] || [ "$STATUS" = "failed" ]; then
                break
              fi

              echo "Scan status: $STATUS (poll $((POLL_COUNT+1)) of $MAX_POLLS)"
              sleep 10
              POLL_COUNT=$((POLL_COUNT+1))
            done

            if [ "$STATUS" = "failed" ]; then
              echo "Scan failed. Please try again."
              exit 1
            elif [ "$STATUS" != "completed" ]; then
              echo "Scan did not complete within 10 minutes."
              exit 1
            fi

            # 3. Get results
            curl -fsS -H "x-api-key: ${RAFTER_API_KEY}" \
              "https://rafter.so/api/static/scan?scan_id=$SCAN_ID" > scan-results.json

            curl -fsS -H "x-api-key: ${RAFTER_API_KEY}" \
              "https://rafter.so/api/static/scan?scan_id=$SCAN_ID&format=md" > scan-results.md


      - name: Check for critical vulnerabilities
        run: |
          if [ ! -s scan-results.json ]; then
            echo "Scan results file is empty or not found."
            exit 0
          fi

          CRITICAL_COUNT=$(jq '.vulnerabilities | map(select(.level=="error")) | length' scan-results.json)

          if [ "$CRITICAL_COUNT" -gt 0 ]; then
            echo "Found $CRITICAL_COUNT critical vulnerabilities!"
            echo "Please review the scan results and fix critical issues before merging."
            exit 1
          else
            echo "No critical vulnerabilities found"
          fi

      - name: Upload scan results
        uses: actions/upload-artifact@v4
        if: always()
        with:
          name: security-scan-results
          path: | 
            scan-results.json
            scan-results.md
          retention-days: 30

Step 4: Test Your Setup

Make a Test Commit

git add .github/workflows/security-scan.yml
git commit -m "Add automated security scanning"
git push

Check GitHub Actions

Go to your repository’s “Actions” tab
Look for the workflow
Verify it runs successfully

AI-Assisted Setup: Copy-Paste Deployment

The AI Assistant Approach

Modern development teams increasingly use AI assistants for rapid setup. Here’s how to leverage Rafter for security scanning configuration:

Step 1: Use This AI Prompt

Copy this prompt to help AI assistants understand the setup process. Any AI assistant will do: vibe coding platforms like Bolt, Lovable, Replit, Emergent, etc all work. Or use your favorite IDE’s built-in AI assistant like Cursor, Claude, ChatGPT, etc.

You are setting up automated security scanning for a software project. Here's what you need to do:

5. **Setup Steps**:
   - Copy this workflow to .github/workflows/security-scan.yml
   - Add your Rafter API key as a GitHub repository secret named RAFTER_API_KEY

This automated approach catches security issues before they reach production, protecting your users and maintaining code quality. Make sure it's set up correctly and securely.


## Workflow

# 1. This file MUST be saved in the following directory: .github/workflows/
#    If the .github/workflows directories don't exist, you'll need to create them.
#
# 2. Add your Rafter API key as a GitHub repository secret:
#    - Go to your repository Settings -> Secrets and variables -> Actions
#    - Click "New repository secret"
#    - Name: RAFTER_API_KEY
#    - Value: your_actual_api_key_here

name: Security Scan with Rafter

on:
  push:
    branches: [ main ]

# Least-privilege permissions (security best practice)
permissions:
  contents: read      # Checkout code
  actions: write      # Upload artifacts

jobs:
  security-scan-three:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Run security scan
        env:
          # Use secrets for your API key
          RAFTER_API_KEY: ${{ secrets.RAFTER_API_KEY }}
        run: |
            set -euo pipefail

            # 1. Trigger scan
            SCAN_ID=$(curl -fsS -X POST \
              -H "Content-Type: application/json" \
              -H "x-api-key: ${RAFTER_API_KEY}" \
              -d '{
                "repository_name": "${{ github.repository }}",
                "branch_name": "${{ github.ref_name }}",
                "scan_mode": "fast"
              }' \
              https://rafter.so/api/static/scan | jq -r '.scan_id')

            echo "SCAN_ID: $SCAN_ID"

            # 2. Wait for completion (polling), for a maximum of 10 minutes (60 loops × 10s = 600s = 10m)
            MAX_POLLS=60
            POLL_COUNT=0
            while [ $POLL_COUNT -lt $MAX_POLLS ]; do
              STATUS=$(curl -fsS -H "x-api-key: ${RAFTER_API_KEY}" \
                "https://rafter.so/api/static/scan?scan_id=$SCAN_ID" | jq -r '.status')

              if [ "$STATUS" = "completed" ] || [ "$STATUS" = "failed" ]; then
                break
              fi

              echo "Scan status: $STATUS (poll $((POLL_COUNT+1)) of $MAX_POLLS)"
              sleep 10
              POLL_COUNT=$((POLL_COUNT+1))
            done

            if [ "$STATUS" = "failed" ]; then
              echo "Scan failed. Please try again."
              exit 1
            elif [ "$STATUS" != "completed" ]; then
              echo "Scan did not complete within 10 minutes."
              exit 1
            fi

            # 3. Get results
            curl -fsS -H "x-api-key: ${RAFTER_API_KEY}" \
              "https://rafter.so/api/static/scan?scan_id=$SCAN_ID" > scan-results.json

            curl -fsS -H "x-api-key: ${RAFTER_API_KEY}" \
              "https://rafter.so/api/static/scan?scan_id=$SCAN_ID&format=md" > scan-results.md


      - name: Check for critical vulnerabilities
        run: |
          if [ ! -s scan-results.json ]; then
            echo "Scan results file is empty or not found."
            exit 0
          fi

          CRITICAL_COUNT=$(jq '.vulnerabilities | map(select(.level=="error")) | length' scan-results.json)

          if [ "$CRITICAL_COUNT" -gt 0 ]; then
            echo "Found $CRITICAL_COUNT critical vulnerabilities!"
            echo "Please review the scan results and fix critical issues before merging."
            exit 1
          else
            echo "No critical vulnerabilities found"
          fi

      - name: Upload scan results
        uses: actions/upload-artifact@v4
        if: always()
        with:
          name: security-scan-results
          path: | 
            scan-results.json
            scan-results.md
          retention-days: 30

Step 3: Follow AI Instructions

Paste the prompt into your AI assistant
Follow the generated instructions step by step
Verify the setup by checking GitHub Actions

Understanding the Workflow Components

Trigger Configuration

on:
  push:
    branches: [ main ]

This configuration ensures scanning runs:

On every push to the main branch
Automatically, without manual intervention

API-Based Scanning

The backend workflow uses Rafter’s API directly instead of installing CLI tools:

- name: Run security scan
  env:
    RAFTER_API_KEY: ${{ secrets.RAFTER_API_KEY }}
  run: |
    set -euo pipefail

    # 1. Trigger scan
    SCAN_ID=$(curl -fsS -X POST \
      -H "Content-Type: application/json" \
      -H "x-api-key: ${RAFTER_API_KEY}" \
      -d '{
        "repository_name": "${{ github.repository }}",
        "branch_name": "${{ github.ref_name }}"
      }' \
      https://rafter.so/api/static/scan | jq -r '.scan_id')

This approach:

Eliminates CLI installation: No need to install tools on the runner
Uses secure API authentication: API key passed via headers

Polling and Status Management

# 2. Wait for completion (polling), for a maximum of 10 minutes
MAX_POLLS=60
POLL_COUNT=0
while [ $POLL_COUNT -lt $MAX_POLLS ]; do
  STATUS=$(curl -fsS -H "x-api-key: ${RAFTER_API_KEY}" \
    "https://rafter.so/api/static/scan?scan_id=$SCAN_ID" | jq -r '.status')

  if [ "$STATUS" = "completed" ] || [ "$STATUS" = "failed" ]; then
    break
  fi

  echo "Scan status: $STATUS (poll $((POLL_COUNT+1)) of $MAX_POLLS)"
  sleep 10
  POLL_COUNT=$((POLL_COUNT+1))
done

The polling mechanism:

Checks every 10 seconds: Balances responsiveness with API load
Handles both success and failure: Exits on completed or failed status
Prevents infinite loops: Maximum 60 polls (10 minutes total)
Provides progress feedback: Shows current status and poll count

Error Handling and Status Management

if [ "$STATUS" = "failed" ]; then
  echo "Scan failed. Please try again."
  exit 1
elif [ "$STATUS" != "completed" ]; then
  echo "Scan did not complete within 10 minutes."
  exit 1
fi

This robust error handling:

Distinguishes failure types: Separate messages for scan failures vs timeouts
Fails builds appropriately: Exits with code 1 to fail the GitHub Action
Provides clear feedback: Specific error messages for different scenarios

Result Retrieval

# 3. Get results
curl -fsS -H "x-api-key: ${RAFTER_API_KEY}" \
  "https://rafter.so/api/static/scan?scan_id=$SCAN_ID" > scan-results.json

curl -fsS -H "x-api-key: ${RAFTER_API_KEY}" \
  "https://rafter.so/api/static/scan?scan_id=$SCAN_ID&format=md" > scan-results.md

The workflow retrieves results in multiple formats:

JSON format: For programmatic processing and vulnerability counting
Markdown format: For human-readable reports and documentation
File output: Saves results to files for artifact upload

Of course, your report will also be immediately available in your dashboard.

Vulnerability Checking

- name: Check for critical vulnerabilities
  run: |
    CRITICAL_COUNT=$(cat scan-results.json | jq '.vulnerabilities | map(select(.level=="error")) | length')
    
    if [ $CRITICAL_COUNT -gt 0 ]; then
      echo "Found $CRITICAL_COUNT critical vulnerabilities!"
      exit 1
    else
      echo "No critical vulnerabilities found"
    fi

This critical step:

Parses scan results using jq
Counts error-level vulnerabilities
Fails the build if critical issues are found
Provides clear feedback to developers

Advanced Configuration Options

While we’ve outlined some powerful use cases below, see our documentation for more advanced configuration options: Rafter CI/CD Documentation.

Customizing Scan Triggers

You can customize when scans run:

# Scan on all branches
on: [push, pull_request]

# Scan only on specific file changes
on:
  push:
    paths:
      - 'src/**'
      - 'package.json'

# Schedule regular scans
on:
  schedule:
    - cron: '0 2 * * 1'  # Every Monday at 2 AM

Adjusting Failure Thresholds

Modify the vulnerability checking logic:

# Fail on warnings and errors
WARNING_COUNT=$(cat scan-results.json | jq '.vulnerabilities | map(select(.level=="warning" or .level=="error")) | length')

# Fail only on specific vulnerability types (using hashed rule IDs)
CRITICAL_COUNT=$(cat scan-results.json | jq '.vulnerabilities | map(select(.ruleId | startswith("R-"))) | length')

# Fail on specific vulnerability patterns
SQL_INJECTION_COUNT=$(cat scan-results.json | jq '.vulnerabilities | map(select(.message | contains("SQL injection"))) | length')

Customizing Polling Behavior

Adjust the polling mechanism for different scan durations:

# For faster scans (reduce polling interval)
sleep 5  # Check every 5 seconds instead of 10

# For longer scans (increase timeout)
MAX_POLLS=120  # 15 minutes instead of 10 (max scan length currently supported by Rafter)

# For more verbose output
echo "Scan status: $STATUS (poll $((POLL_COUNT+1)) of $MAX_POLLS) - $(date)"

Adding Notifications

Integrate with Slack, Discord, or email:

- name: Notify on failure
  if: failure()
  uses: 8398a7/action-slack@v3
  with:
    status: failure
    text: "Security scan failed: ${{ github.event.head_commit.message }}"

Troubleshooting Common Issues

API Key Not Found

Error: Error: RAFTER_API_KEY environment variable not set Solution:

Verify the secret exists in GitHub repository settings
Check the secret name matches exactly: RAFTER_API_KEY
Ensure the workflow uses ${{ secrets.RAFTER_API_KEY }}

Scan Request Fails

Error: curl: (22) The requested URL returned error: 401 or curl: (22) The requested URL returned error: 400 Solution:

401 Unauthorized: Check your API key is valid and not expired
400 Bad Request: Verify repository name format (should be owner/repo)
Network issues: The -fsS flags will cause curl to fail silently on HTTP errors
Branch name issues: Ensure ${{ github.ref_name }} returns the correct branch name

Scan Status Issues

Error: Scan stuck in “processing” or “pending” status Solution:

Timeout handling: The workflow automatically fails after 10 minutes
Status checking: Verify the API returns valid status values (completed, failed, processing, pending)
Polling frequency: Adjust sleep 10 if scans typically take longer
API rate limits: Check if you’re hitting API rate limits

Scan Results Not Found

Error: scan-results.json: No such file or directory Solution:

Check scan completion: Ensure the scan reached “completed” status
Verify file output: The workflow saves results to scan-results.json and scan-results.md
API response format: Confirm the API returns results in the expected JSON format
Error handling: The set -euo pipefail ensures the script fails if curl commands fail

Security Best Practices

API Key Management

Rotate keys regularly: Generate new keys every 90 days
Monitor usage: Check API key usage logs for anomalies
Use least privilege: Only grant necessary permissions
Never log keys: Ensure keys don’t appear in logs or outputs

Workflow Security

Pin action versions: Use specific commit SHAs instead of tags
Review permissions: Limit workflow permissions to minimum required
Audit regularly: Review workflow changes and access patterns
Use trusted sources: Only use official GitHub Actions

Repository Security

Enable branch protection: Require status checks before merging
Use required reviewers: Require security team review for workflow changes
Monitor secrets: Regularly audit repository secrets
Enable security alerts: Use GitHub’s security features

Measuring Success

Key Metrics to Track

Scan Coverage: Percentage of commits scanned
Detection Rate: Vulnerabilities found per scan
Fix Time: Average time from detection to resolution
False Positive Rate: Incorrect vulnerability reports

Success Indicators

Zero critical vulnerabilities in production deployments
Consistent scan execution across all branches
Rapid vulnerability resolution (under 24 hours)
Developer adoption of security-first practices

Conclusion

Automated security scanning transforms security from a manual, error-prone process into a seamless part of your development workflow. By catching vulnerabilities before they reach production, you protect your users, your reputation, and your bottom line. The setup process takes just 5 minutes, but the protection lasts for the lifetime of your project. Whether you prefer the zero-config local scan or the full backend SAST scan, the result is the same: security coverage that runs automatically on every commit. Start with the basic workflow, customize it for your needs, and watch your security posture improve with every deployment.

Get Started

CLI Guides

Agent Security

References

​Two CI Modes

​Mode 1: Local Scan (no API key required)

​Mode 2: Backend Scan (API key required)

​Introduction

​Why Automated Security Scanning Matters

​The Manual Scanning Problem

​The Automated Solution

​Understanding API Keys in CI/CD

​What Are API Keys?

​Why API Keys Are Secure

​How GitHub Secrets Protect Your Keys

​Manual Setup: Step-by-Step Configuration

​Step 1: Choose Your Mode

​Step 2: Get Your Rafter API Key

​Step 3: Create GitHub Workflow

​Step 4: Test Your Setup

​AI-Assisted Setup: Copy-Paste Deployment

​The AI Assistant Approach

​Step 1: Use This AI Prompt

​Step 3: Follow AI Instructions

​Understanding the Workflow Components

​Trigger Configuration

​API-Based Scanning

​Polling and Status Management

​Error Handling and Status Management

​Result Retrieval

​Vulnerability Checking

​Advanced Configuration Options

​Customizing Scan Triggers

​Adjusting Failure Thresholds

​Customizing Polling Behavior

​Adding Notifications

​Troubleshooting Common Issues

​API Key Not Found

​Scan Request Fails

​Scan Status Issues

​Scan Results Not Found

​Security Best Practices

​API Key Management

​Workflow Security

​Repository Security

​Measuring Success

​Key Metrics to Track

​Success Indicators

​Conclusion

Two CI Modes

Mode 1: Local Scan (no API key required)

Mode 2: Backend Scan (API key required)

Introduction

Why Automated Security Scanning Matters

The Manual Scanning Problem

The Automated Solution

Understanding API Keys in CI/CD

What Are API Keys?

Why API Keys Are Secure

How GitHub Secrets Protect Your Keys

Manual Setup: Step-by-Step Configuration

Step 1: Choose Your Mode

Step 2: Get Your Rafter API Key

Step 3: Create GitHub Workflow

Step 4: Test Your Setup

AI-Assisted Setup: Copy-Paste Deployment

The AI Assistant Approach

Step 1: Use This AI Prompt

Step 3: Follow AI Instructions

Understanding the Workflow Components

Trigger Configuration

API-Based Scanning

Polling and Status Management

Error Handling and Status Management

Result Retrieval

Vulnerability Checking

Advanced Configuration Options

Customizing Scan Triggers

Adjusting Failure Thresholds

Customizing Polling Behavior

Adding Notifications

Troubleshooting Common Issues

API Key Not Found

Scan Request Fails

Scan Status Issues

Scan Results Not Found

Security Best Practices

API Key Management

Workflow Security

Repository Security

Measuring Success

Key Metrics to Track

Success Indicators

Conclusion