> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rafter.so/llms.txt
> Use this file to discover all available pages before exploring further.

# Advanced

> Discover advanced CLI features, automation techniques, and integration patterns for Rafter security.

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

```bash theme={null}
# 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

# 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 --mode plus --quiet -k "RFabc-custom-key"
```

### `rafter get` - Retrieval Options

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
# 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](/guides/ci-cd).

## Automation Techniques

### Shell Scripting

Create reusable scripts for common workflows:

```bash theme={null}
#!/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:

```bash theme={null}
# 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 error-level issues
HIGH_ISSUES=$(rafter get $SCAN_ID --format json | jq '.vulnerabilities | map(select(.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](/api-reference/endpoint/static/get#scan-completed-json-format), which makes it easy to process with `jq`. At the top level is various details about the scan, including a vulnerabilities object in [SARIF](https://sarifweb.azurewebsites.net/) 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.

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
# 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.

```bash expandable theme={null}
#!/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:

```bash theme={null}
# 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

<CardGroup cols={2}>
  <Card title="CLI Basics" icon="terminal" href="/guides/basics">
    Learn the fundamentals of using the Rafter CLI.
  </Card>

  <Card title="Advanced CLI" icon="terminal" href="/guides/advanced">
    Master advanced CLI features and automation.
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/introduction">
    Build custom integrations with the REST API.
  </Card>

  <Card title="CI/CD Integration" icon="git-merge" href="/guides/ci-cd">
    Set up automated scanning in your pipelines.
  </Card>
</CardGroup>