Skip to main content

​
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

# Non-interactive mode for automation, no status updates
rafter run --quiet

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

​
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
if rafter run --quiet | 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=$(RESULTS | 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

​
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
RESULTS=$(rafter run --quiet --format json)

# Check for high/critical issues
HIGH_ISSUES=$(rafter get $SCAN_ID --format json | jq '.vulnerabilities | map(select(.level=="high" or .level=="error")) | length')

if [ $HIGH_ISSUES -gt 0 ]; then
    echo "❌ Security scan found $HIGH_ISSUES critical issues"
    echo "Run 'rafter get $SCAN_ID' for details"
    exit 1
fi

echo "✅ Security scan passed"

​
Output Processing

Rafter defaults to reporting results in JSON format following our API Schema, which makes it easy to process with jq. At the top level is various details about the scan, including a vulnerabilities object in SARIF format, an industry-standard format for security scanning results.

​
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)

# Option 2: Get results from an existing scan
RESULTS=$(rafter get <scan-id>)
Next, we’ll demonstrate many common use cases for processing the results object.

​
Basic Analysis

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

# Find files with most vulnerabilities
echo "$RESULTS" | jq -r '.vulnerabilities[].file' | 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(.level=="error")) | length),
    warning: (.vulnerabilities | map(select(.level=="warning")) | length),
    note: (.vulnerabilities | map(select(.level=="note")) | length)
}'

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

​
Data Extraction

# Extract specific fields to CSV format
echo "$RESULTS" | jq -r '.vulnerabilities[] | [.level, .rule_id, .file, .line, .message] | @csv'

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

# Extract rule IDs and their counts
echo "$RESULTS" | jq -r '.vulnerabilities[].ruleId' | 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 level
CRITICAL=$(echo "$RESULTS" | jq -r '.vulnerabilities[] | select(.level == "error") | .ruleId' | wc -l)
HIGH=$(echo "$RESULTS" | jq -r '.vulnerabilities[] | select(.level == "warning") | .ruleId' | wc -l)
MEDIUM=$(echo "$RESULTS" | jq -r '.vulnerabilities[] | select(.level == "note") | .ruleId' | wc -l)
LOW=$(echo "$RESULTS" | jq -r '.vulnerabilities[] | select(.level == "none") | .ruleId' | wc -l)

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

# Show top rule violations
echo "Top Security Rule Violations"
echo "---------------------------"
echo "$RESULTS" | jq -r '.vulnerabilities[] | .ruleId' | 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(.level == "error" or .level == "warning") | "\(.level | ascii_upcase): \(.ruleId) - \(.message)"' | 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[] | .ruleId' | 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(.level == "error") | "\(.file)\nLine: \(.line)\nRule: \(.ruleId)\nMessage: \(.message)\n---"' | head -10
echo ""

# Show high severity issues with locations
echo "Warning by File"
echo "-------------------"
echo "$RESULTS" | jq -r '.vulnerabilities[] | select(.level == "warning") | "\(.file):\(.line) - \(.ruleId): \(.message)"' | head -10
echo ""

# Show Note severity issues with locations
echo "Note by File"
echo "-------------------"
echo "$RESULTS" | jq -r '.vulnerabilities[] | select(.level == "note") | "\(.file):\(.line) - \(.ruleId): \(.message)"' | 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.