Advanced

Advanced CLI Usage

Once you’re comfortable with the basics, explore these advanced features to enhance your security scanning workflows.

Advanced Command Options

`rafter run` - Scanning Options

# Specify custom repository and branch
rafter run --repo myorg/myrepo --branch feature/new-feature

# Use custom API key (overrides environment variable)
rafter run --api-key "RFabc-custom-key"

# Output in specific format
rafter run --format md

# Choose scan mode (fast or plus)
rafter run --mode plus --format md
rafter run -m plus --format md

# Suppress status messages, but still wait for the scan to finish
rafter run --quiet

# Fire-and-forget — submit the scan and exit immediately without polling.
# With --quiet this prints nothing at all, not even the scan ID — drop
# --quiet if you need the ID to retrieve results later with `rafter get`.
rafter run --quiet --skip-interactive

# Combine multiple options for versatile automation
rafter run --repo myorg/myrepo --branch main --format md --mode plus --quiet -k "RFabc-custom-key"

--mode plus spends credits. If the approval gate is enabled — scan.plus_requires_approval in .rafter.yml, or agent.scan.plusRequiresApproval in the global config (off by default) — a non-interactive --mode plus run like the one above refuses with exit code 5 unless you add -y/--yes or set RAFTER_CONFIRM=1.

`rafter get` - Retrieval Options

# Wait for scan completion with polling
rafter get <scan-id> --interactive

# Get results in specific format
rafter get <scan-id> --format md

# Suppress status messages
rafter get <scan-id> --quiet

# Use custom API key
rafter get <scan-id> --api-key "RFabc-custom-key"

Common Use Cases

Local Development

# Quick scan during development
rafter run --format md

# Save results to a file
rafter run --format md > security-report-$(date +%Y-%m-%d-%H-%M-%S).md

Feature Branch Workflow

# Scan your feature branch
rafter run --branch feature/new-feature

# Get results in Markdown (with prompting for your favorite AI)
rafter run --branch feature/new-feature --format md  > rafter-report-$(date +%Y-%m-%d-%H-%M-%S).md

CI/CD Integration

# Check results in scripts — --format json is required; the CLI defaults to md
if rafter run --quiet --format json | jq -e '.vulnerabilities | length > 0'; then
    echo "Security issues found!"
    exit 1
fi

See more on our CD/CI page.

Automation Techniques

Shell Scripting

Create reusable scripts for common workflows:

#!/bin/bash
# scan-and-report.sh

# Run scan and capture results
RESULTS=$(rafter run --quiet --format json)

# Check for critical vulnerabilities (or any other severity)
CRITICAL_COUNT=$(echo "$RESULTS" | jq '.vulnerabilities | map(select(.severity=="error")) | length')

if [ $CRITICAL_COUNT -gt 0 ]; then
    echo "❌ Found $CRITICAL_COUNT critical vulnerabilities!"
    exit 1
else
    echo "✅ No critical vulnerabilities found"
fi

Pipeline Integration

Integrate with your existing development pipelines:

# Pre-commit hook example
#!/bin/bash
# .git/hooks/pre-commit

# Only scan if we have API key
if [ -z "$RAFTER_API_KEY" ]; then
    echo "Skipping security scan - no API key set"
    exit 0
fi

# Run scan and capture results (rafter run waits for completion by default)
RESULTS=$(rafter run --quiet --format json)

# Check for error-level issues
HIGH_ISSUES=$(echo "$RESULTS" | jq '.vulnerabilities | map(select(.severity=="error")) | length')

if [ "$HIGH_ISSUES" -gt 0 ]; then
    SCAN_ID=$(echo "$RESULTS" | jq -r '.scan_id')
    echo "❌ Security scan found $HIGH_ISSUES critical issues"
    echo "Run 'rafter get $SCAN_ID --format md' for a human-readable report"
    exit 1
fi

echo "✅ Security scan passed"

Output Processing

--format json returns results following our API Schema, which makes them easy to process with jq. The CLI’s own default format is md, so pass --format json explicitly for scripting. At the top level is various details about the scan, including a vulnerabilities array. Each finding’s severity is one of the SARIF levels error, warning or note.

Setup for JSON Processing

First, set up your results object either from a scan run or by getting existing results.

# Option 1: Run a new scan and capture results
RESULTS=$(rafter run --quiet --format json)

# Option 2: Get results from an existing scan
RESULTS=$(rafter get <scan-id> --format json)

Next, we’ll demonstrate many common use cases for processing the results object.

Basic Analysis

# Extract all vulnerability levels
echo "$RESULTS" | jq -r '.vulnerabilities[].severity' | sort | uniq -c

# Find files with most vulnerabilities
echo "$RESULTS" | jq -r '.vulnerabilities[].file_path' | sort | uniq -c | sort -nr

# Count total vulnerabilities
echo "$RESULTS" | jq '.vulnerabilities | length'

Summary Reports

# Create comprehensive summary
echo "$RESULTS" | jq '{
    scan_id: .scan_id,
    total_vulnerabilities: (.vulnerabilities | length),
    error: (.vulnerabilities | map(select(.severity=="error")) | length),
    warning: (.vulnerabilities | map(select(.severity=="warning")) | length),
    note: (.vulnerabilities | map(select(.severity=="note")) | length)
}'

# Filter by severity level
echo "$RESULTS" | jq '.vulnerabilities[] | select(.severity=="error" or .severity=="warning")'

Data Extraction

# Extract specific fields to CSV format
echo "$RESULTS" | jq -r '.vulnerabilities[] | [.severity, .rule_id, .file_path, .line_start, .title] | @csv'

# Get all file paths with vulnerabilities
echo "$RESULTS" | jq -r '.vulnerabilities[].file_path' | sort | uniq

# Extract rule IDs and their counts
echo "$RESULTS" | jq -r '.vulnerabilities[].rule_id' | sort | uniq -c

Complete Analysis Processing Script

Below is a complete script that runs a Rafter security scan and processes the JSON results.

#!/bin/bash

# Rafter Security Scan Analysis Script
# Analyzes Rafter output for security vulnerabilities and provides actionable insights

echo "Rafter Security Scan Analysis"
echo "============================="
echo ""

# Run Rafter scan and capture results
echo "Running Rafter security scan..."
RESULTS=$(rafter run --quiet --format json)

if [ $? -ne 0 ]; then
    echo "Error running Rafter scan"
    exit 1
fi

# Check if we got results
if [ -z "$RESULTS" ]; then
    echo "No results returned from Rafter scan"
    exit 0
fi

echo "Scan completed successfully"
echo ""

# Parse the custom Rafter JSON format and extract key metrics
echo "Security Scan Summary"
echo "--------------------"

# Extract scan metadata
REPO_NAME=$(echo "$RESULTS" | jq -r '.repository_name // "unknown"')
BRANCH_NAME=$(echo "$RESULTS" | jq -r '.branch_name // "unknown"')
SCAN_DATE=$(echo "$RESULTS" | jq -r '.scan_date // "unknown"')
STATUS=$(echo "$RESULTS" | jq -r '.status // "unknown"')

echo "Repository: $REPO_NAME"
echo "Branch: $BRANCH_NAME"
echo "Scan Date: $SCAN_DATE"
echo "Status: $STATUS"
echo ""

# Count total vulnerabilities
TOTAL_VULNS=$(echo "$RESULTS" | jq -r '.vulnerabilities | length // 0')
echo "Total Vulnerabilities: $TOTAL_VULNS"

if [ "$TOTAL_VULNS" -eq 0 ]; then
    echo "No security issues found! Your codebase appears secure."
    exit 0
fi

# Count by severity — the values are error, warning and note
CRITICAL=$(echo "$RESULTS" | jq -r '.vulnerabilities[] | select(.severity == "error") | .rule_id' | wc -l)
HIGH=$(echo "$RESULTS" | jq -r '.vulnerabilities[] | select(.severity == "warning") | .rule_id' | wc -l)
MEDIUM=$(echo "$RESULTS" | jq -r '.vulnerabilities[] | select(.severity == "note") | .rule_id' | wc -l)

echo "Critical: $CRITICAL"
echo "Warning: $HIGH"
echo "Note: $MEDIUM"
echo ""

# Show top rule violations
echo "Top Security Rule Violations"
echo "---------------------------"
echo "$RESULTS" | jq -r '.vulnerabilities[] | .rule_id' | sort | uniq -c | sort -nr | head -10 | while read count rule; do
    echo "$count violations: $rule"
done
echo ""

# Show critical and high severity findings
echo "Critical & High Severity Findings"
echo "--------------------------------"
echo "$RESULTS" | jq -r '.vulnerabilities[] | select(.severity == "error" or .severity == "warning") | "\(.severity | ascii_upcase): \(.rule_id) - \(.title)"' | head -20

if [ $((CRITICAL + HIGH)) -gt 20 ]; then
    echo "... and $((CRITICAL + HIGH - 20)) more critical/high findings"
fi
echo ""

# Show specific vulnerability types with better categorization
echo "Vulnerability Categories"
echo "-----------------------"
echo "$RESULTS" | jq -r '.vulnerabilities[] | .rule_id' | grep -E "(sql|injection|xss|csrf|auth|secret|key|weak|crypto|mocked|problematic)" | sort | uniq -c | sort -nr | head -10 | while read count vuln; do
    echo "$count: $vuln"
done
echo ""

# Show code locations for critical issues
echo "Critical Issue by File"
echo "-----------------------"
echo "$RESULTS" | jq -r '.vulnerabilities[] | select(.severity == "error") | "\(.file_path)\nLine: \(.line_start)\nRule: \(.rule_id)\nMessage: \(.title)\n---"' | head -10
echo ""

# Show high severity issues with locations
echo "Warning by File"
echo "-------------------"
echo "$RESULTS" | jq -r '.vulnerabilities[] | select(.severity == "warning") | "\(.file_path):\(.line_start) - \(.rule_id): \(.title)"' | head -10
echo ""

# Show Note severity issues with locations
echo "Note by File"
echo "-------------------"
echo "$RESULTS" | jq -r '.vulnerabilities[] | select(.severity == "note") | "\(.file_path):\(.line_start) - \(.rule_id): \(.title)"' | head -10
echo ""

echo ""
echo "Analysis complete. Review findings and prioritize fixes based on severity."
echo ""
echo "Scan Summary: $TOTAL_VULNS total issues found in $REPO_NAME ($BRANCH_NAME)"

Markdown Processing

Process Markdown output for documentation:

# Generate report for GitHub
rafter get <scan-id> --format md > SECURITY_SCAN.md

# Add to pull request
echo "## Security Scan Results" >> PR_DESCRIPTION.md
rafter get <scan-id> --format md >> PR_DESCRIPTION.md

Next Steps

CLI Basics

Learn the fundamentals of using the Rafter CLI.

Advanced CLI

Master advanced CLI features and automation.

API Reference

Build custom integrations with the REST API.

CI/CD Integration

Set up automated scanning in your pipelines.

Get Started

CLI Guides

Local Security

Advanced CLI Usage

Advanced Command Options

`rafter run` - Scanning Options

`rafter get` - Retrieval Options

Common Use Cases

Local Development

Feature Branch Workflow

CI/CD Integration

Automation Techniques

Shell Scripting

Pipeline Integration

Output Processing

Setup for JSON Processing

Basic Analysis

Summary Reports

Data Extraction

Complete Analysis Processing Script

Markdown Processing

Next Steps

CLI Basics

Advanced CLI

API Reference

CI/CD Integration

​Advanced CLI Usage

​Advanced Command Options

​rafter run - Scanning Options

​rafter get - Retrieval Options

​Common Use Cases

​Local Development

​Feature Branch Workflow

​CI/CD Integration

​Automation Techniques

​Shell Scripting

​Pipeline Integration

​Output Processing

​Setup for JSON Processing

​Basic Analysis

​Summary Reports

​Data Extraction

​Complete Analysis Processing Script

​Markdown Processing

​Next Steps

CLI Basics

Advanced CLI

API Reference

CI/CD Integration

Advanced CLI Usage

Advanced Command Options

`rafter run` - Scanning Options

`rafter get` - Retrieval Options

Common Use Cases

Local Development

Feature Branch Workflow

CI/CD Integration

Automation Techniques

Shell Scripting

Pipeline Integration

Output Processing

Setup for JSON Processing

Basic Analysis

Summary Reports

Data Extraction

Complete Analysis Processing Script

Markdown Processing

Next Steps