Skip to content

README.md

Latest commit

 

History

History
203 lines (155 loc) · 6.61 KB

README.md

File metadata and controls

203 lines (155 loc) · 6.61 KB
Raw

Aardvark-Style AI Security Scanning System

Python Node.js Go Docker GitHub Actions OpenAI Semgrep Bandit Trivy Flask Express License

An automated security scanning system that uses AI-powered triage, sandbox validation, and automated patch suggestions to identify and fix security vulnerabilities in code repositories.

Architecture

Gemini_Generated_Image_aa75vxaa75vxaa75 
graph TB
    A[GitHub Actions Trigger] --> B[Scanner Layer]
    B --> C[Semgrep]
    B --> D[Bandit]
    B --> E[Trivy]
    C --> F[JSON Findings]
    D --> F
    E --> F
    F --> G[Triage Agent]
    G --> H[Secret Scrubbing]
    H --> I[LLM Analysis]
    I --> J[Triage Report]
    J --> K[Sandbox Validator]
    K --> L[Docker Container]
    L --> M[POC Execution]
    M --> N[Sandbox Results]
    N --> O{Patch Automation?}
    O -->|AUTO_OPEN_PR=true| P[Create Branch]
    O -->|AUTO_OPEN_PR=false| Q[Report Only]
    P --> R[Apply Patch]
    R --> S[Run Tests]
    S --> T{Tests Pass?}
    T -->|Yes| U[Create PR]
    T -->|No| V[Create Issue]
    U --> W[PR Comment]
    V --> W
    Q --> W
Loading

Features

  • Multi-Tool Scanning: Integrates Semgrep, Bandit, and Trivy for comprehensive vulnerability detection
  • AI-Powered Triage: Uses LLM to analyze findings, assign severity, and suggest patches
  • Sandbox Validation: Safely executes proof-of-concept exploits in isolated Docker containers
  • Automated Patching: Creates branches, applies fixes, runs tests, and opens PRs (when enabled)
  • Strong Guardrails: Secret scrubbing, rate limiting, audit logging, and safety controls
  • Multi-Language Support: Works with Python, JavaScript/Node.js, and Go

Quick Start

Prerequisites

  • Python 3.11+
  • Docker (for sandbox execution)
  • Git
  • semgrep CLI installed
  • bandit CLI installed
  • trivy CLI (optional)

Local Setup

  1. Clone the repository:
git clone https://github.com/Ashutosh0x/aardvark-security-scanner.git
cd aardvark-security-scanner
  1. Install dependencies:
make setup
  1. Configure the system:
cp config.yaml config.local.yaml
# Edit config.local.yaml with your settings
  1. Set required environment variables:
export OPENAI_API_KEY="your-api-key"  # Required for LLM triage
export GITHUB_TOKEN="your-token"      # Required for PR automation
  1. Run a local scan:
make run-local-scan

GitHub Actions Setup

  1. Add the following secrets to your repository:

    • OPENAI_API_KEY: Your OpenAI API key (or compatible endpoint)
    • GITHUB_TOKEN: Automatically provided by GitHub Actions (for PR creation)

  2. Configure config.yaml in your repository:

    • Set auto_open_pr: false by default (enable only when ready)
    • Adjust fail_on_critical based on your security policy
    • Configure max_tokens and other limits

  3. The workflow will automatically run on:

    • Pull requests (opened, synchronize, reopened)
    • Pushes to protected branches
    • Manual trigger via workflow_dispatch

Configuration

Edit config.yaml to customize behavior:

  • allowed_domains: Whitelist for network access in sandbox
  • max_tokens: LLM token budget per request
  • redact_patterns: Custom regex patterns for secret detection
  • fail_on_critical: Fail CI job if critical findings exist
  • auto_open_pr: Enable automatic PR creation (default: false)
  • sandbox_timeout_seconds: Maximum execution time for sandbox
  • llm_endpoint: LLM API endpoint (defaults to OpenAI)
  • data_retention_days: How long to keep artifacts (default: 30)

Safety Features

  • Secret Protection: All secrets are redacted before sending to LLM
  • Sandbox Isolation: Network disabled by default, resource limits enforced
  • Human Review Gate: PR automation disabled by default
  • Audit Logging: All LLM calls logged with correlation IDs
  • Data Retention: Automatic cleanup of old artifacts

Sample Vulnerable Apps

The repository includes sample applications demonstrating common vulnerabilities:

  • sample-app/python-vuln/: Flask app with hardcoded secrets and insecure token handling
  • sample-app/js-vuln/: Node.js app with command injection vulnerability
  • sample-app/go-vuln/: Go app with SQL injection vulnerability

Run the demo:

./demo/run_demo.sh

Testing

Run unit tests:

make test

Run specific test suites:

pytest tests/test_scrub_secrets.py
pytest tests/test_triage_prompt.py
pytest tests/test_patch_apply.py

Workflow

  1. Scanning: Security scanners analyze the codebase
  2. Triage: LLM analyzes findings and suggests patches
  3. Validation: Sandbox verifies exploit reproducibility
  4. Remediation: Patches applied and PRs created (if enabled)
  5. Reporting: Results posted as PR comments and artifacts

Output

The system generates:

  • out/triage_report.json: Structured findings with severity and patches
  • out/sandbox_results.json: Sandbox validation results
  • logs/: Rotating audit logs
  • metrics.json: Runtime statistics and token usage

License

MIT License - see LICENSE file for details.

Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Add tests
  5. Submit a pull request

Security

If you discover a security vulnerability, please email ashutoshkumarsingh0x@gmail.com instead of opening a public issue.

Built with 💖 OPENAI