RAKṢĀ — Security ScannerQuick Start

Quick Start Guide

Get RAKṢĀ running in 5 minutes and perform your first security scan.

Prerequisites

  • Docker installed on your system
  • Internet connection for image download
  • A code repository or archive to scan

Step 1: Pull and Run RAKṢĀ

# Pull the latest image from GitHub Container Registry
docker pull ghcr.io/gaurav21/raksha:latest
 
# Run RAKṢĀ with default settings
docker run -d \
  --name raksha \
  -p 8430:8080 \
  ghcr.io/gaurav21/raksha:latest
 
# Check if it's running
curl http://localhost:8430/health

Expected response:

{
  "status": "ok",
  "scanners": ["raksha-patterns", "semgrep", "bandit"],
  "total_scans": 0
}

Step 2: Your First Scan

Option A: Scan a GitHub Repository

# Scan a popular project
curl -X POST "http://localhost:8430/scan/github" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://github.com/django/django",
    "branch": "main"
  }'

Option B: Upload an Archive

# Create a test archive from your current project
zip -r myproject.zip . -x "*.git*" "node_modules/*" "__pycache__/*"
 
# Upload and scan
curl -X POST "http://localhost:8430/scan/upload" \
  -F "file=@myproject.zip"

Step 3: Review Results

The scan response includes a scan_id. Use it to retrieve detailed results:

# Replace {scan_id} with the actual ID from your scan
curl http://localhost:8430/scan/{scan_id}

Sample Output

{
  "scan_id": "a1b2c3d4e5f6",
  "source": "django/django",
  "source_type": "github",
  "scan_time": "2024-05-11T13:30:45Z",
  "duration_seconds": 12.5,
  "total_files": 245,
  "scanned_files": 203,
  "total_findings": 8,
  "findings_by_severity": {
    "critical": 0,
    "high": 1,
    "medium": 3,
    "low": 4,
    "info": 0
  },
  "findings": [
    {
      "id": "RAKSHA-001-a1b2",
      "title": "Potential SQL Injection",
      "description": "Raw SQL query construction detected",
      "severity": "high",
      "file": "myapp/models.py",
      "line": 45,
      "code_snippet": "query = f\"SELECT * FROM users WHERE id = {user_id}\"",
      "scanner": "raksha-patterns",
      "cwe": "CWE-89",
      "remediation": "Use parameterized queries or ORM methods"
    }
  ]
}

Step 4: Web Interface (Optional)

Open your browser to http://localhost:8430 to access the web interface for:

  • Drag-and-drop file upload
  • GitHub URL scanning
  • Interactive result browsing
  • One-click result export

Step 5: Export Results

# Download results as JSON file
curl -o scan-results.json "http://localhost:8430/scan/{scan_id}/export"

Next Steps

Customize Your Setup

  1. Configure Scanners — Enable/disable engines, custom rules
  2. CI/CD Integration — Automate scanning in your pipeline
  3. Deployment Options — Production deployments with Docker Compose

Advanced Usage

# Scan with custom environment
docker run -d \
  --name raksha-custom \
  -p 8430:8080 \
  -e MAX_UPLOAD_MB=100 \
  -e DD_API_KEY=your_datadog_key \
  -v /path/to/custom-rules:/app/rules \
  ghcr.io/gaurav21/raksha:latest
 
# Multiple concurrent scans
for repo in "owner/repo1" "owner/repo2" "owner/repo3"; do
  curl -X POST "http://localhost:8430/scan/github" \
    -H "Content-Type: application/json" \
    -d "{\"url\": \"https://github.com/$repo\"}" &
done
wait

Troubleshooting

Common Issues

Port Already in Use:

# Use a different port
docker run -p 8431:8080 ghcr.io/gaurav21/raksha:latest

Large Files Rejected:

# Increase upload limit
docker run -e MAX_UPLOAD_MB=100 ghcr.io/gaurav21/raksha:latest

Scanner Not Found:

# Check available scanners
curl http://localhost:8430/health | jq '.scanners'

Performance Tuning

# For high-throughput environments
docker run -d \
  --name raksha-performance \
  -p 8430:8080 \
  --memory=4g \
  --cpus=2 \
  -e SCAN_UPLOAD_DIR=/tmp/raksha-scans \
  -e WORKERS=4 \
  ghcr.io/gaurav21/raksha:latest

You’re now ready to integrate RAKṢĀ into your security workflow!

Next: API Reference for detailed endpoint documentation.

OverviewAPI Reference