CI/CD Integration

​

Fastest Path: rafter ci init

rafter ci init                    # auto-detect platform
rafter ci init --platform github  # explicit
rafter ci init --with-backend     # include remote code analysis job (requires RAFTER_API_KEY)

​

Two CI Modes

​

Mode 1: Local Secret Scanning (no API key required)

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

​

Mode 2: Backend Code Analysis (API key required)

​

Introduction

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

​

Why Automated Security Scanning Matters

​

The Manual Scanning Problem

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

​

The Automated Solution

• 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?

​

Why API Keys Are Secure

• 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

• 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

​

Step 2: Get Your Rafter API Key

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

1. Click “Generate New API Key” or “Refresh API Key”
2. 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.

1. Navigate to your GitHub repository
2. Click “Settings” → “Secrets and variables” → “Actions”
3. Click “New repository secret”
4. Name: RAFTER_API_KEY
5. Value: Paste your API key
6. Click “Add secret”

​

Step 3: Create GitHub Workflow

mkdir -p .github/workflows

# .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 secrets . --json --quiet

# .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: Rafter Code Analysis

on:
  push:
    branches: [ main ]

permissions:
  contents: read

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

      - name: Install Rafter CLI
        run: npm install -g @rafter-security/cli

      - name: Run code analysis
        env:
          RAFTER_API_KEY: ${{ secrets.RAFTER_API_KEY }}
        run: rafter run --format json --quiet > scan-results.json

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

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

​

Step 4: Test Your Setup

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

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

​

AI-Assisted Setup

Set up Rafter security scanning for this repo. Run `rafter ci init --platform github`
to generate the workflow, then commit it. If we have a RAFTER_API_KEY, use --with-backend
for full SAST code analysis. Otherwise the local secret scan is fine.

rafter ci init --platform github --with-backend
# Review .github/workflows/rafter-security.yml, then commit and push

​

Understanding the Workflow Components

​

Trigger Configuration

on:
  push:
    branches: [ main ]

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

​

CLI-Based Code Analysis

- name: Run code analysis
  env:
    RAFTER_API_KEY: ${{ secrets.RAFTER_API_KEY }}
  run: rafter run --format json --quiet > scan-results.json

• Auto-detects repo and branch from the git checkout
• Polls until complete — no manual loop needed
• Returns structured JSON with consistent schema and documented exit codes

​

Exit Codes

​

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

• 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

​

Customizing Triggers

# 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

# 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')

​

Adding Notifications

- 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

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

​

Scan Request Fails

• 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

• 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

• 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