Codebuster — Unified Offline Security Scanner

Codebuster is a single-command, multi-module security scanner:

SAST – Static Application Security Testing
Secrets – Hardcoded credential & token detection (including Git history)
SCA – Software Composition Analysis (dependency CVEs)
DAST – Dynamic Application Security Testing for web targets
Nuclei – Template-based HTTP checks
IaC – Infrastructure-as-Code misconfiguration checks

Codebuster is designed to cover code, configuration, dependencies, and live web services from one CLI, with a consistent finding model and unified reporting.

Features

Unified CLI

One install, one command.
Automatically selects appropriate modules based on targets (paths vs URLs).
Familiar-style flags such as -sS, -T, -A, --script, -oH, -oJ, -oS, -oN, -oA.

SAST

Regex and AST-based rules.
Taint tracking and data-flow analysis for deeper vulnerabilities.
Multi-language support (Python, JavaScript/TypeScript, Java, Go, PHP, Ruby, C/C++, C#, Rust, Kotlin, Swift, Shell, YAML, Terraform, and more).
Targets common categories:
- Injection (SQL, command, template, LDAP, etc.)
- Path traversal and local file inclusion
- Hardcoded secrets and credentials
- Weak cryptography and insecure randomness
- Insecure deserialization
- XSS, SSRF, XXE
- Security misconfigurations
- ReDoS and unsafe regular expressions
- Memory safety issues in low-level languages

Secrets

Hundreds of patterns across cloud, CI/CD, payments, messaging, SaaS, databases, AI/ML, and generic keys.
Shannon entropy detection for unknown token formats.
Git history scanning to catch secrets in old commits.
Safe redaction of detected secrets in output (only partial fragments shown).

SCA

Offline CVE database with multiple ecosystems:
- Python packages, JavaScript packages, Java artifacts, Go modules, Ruby gems, Rust crates, PHP packages.
Support for many manifest formats:
- requirements.txt, Pipfile.lock, pyproject.toml
- package.json, package-lock.json, yarn.lock
- pom.xml, go.mod, Gemfile.lock, Cargo.lock, composer.lock
Version range comparison, severity mapping, and remediation hints.

DAST

Web crawler for HTTP/HTTPS targets with link and form extraction.
Passive checks:
- Missing or weak security headers
- Insecure cookies
- Verbose server info and error pages
- CORS and framing issues
Active checks:
- SQL injection
- Cross-site scripting
- Local file inclusion / path traversal
- Open redirect
- Indicators of missing CSRF protection
Dangerous path checks (config files, backups, admin panels, debug endpoints, metadata URLs).
SSL/TLS configuration inspection.
Rate limiting, proxy configuration, custom user-agent and authentication options.

Nuclei-style Scanner

YAML templates for:
- Known vulnerabilities
- Exposed admin and monitoring panels
- Sensitive file exposure
- Misconfigurations and default credentials
- Technology fingerprinting
Script categories:
- vuln, discovery, auth, safe, intrusive, all.

IaC

Scans Terraform, Kubernetes manifests, Dockerfiles, CloudFormation, and Ansible playbooks.
Flags insecure defaults and misconfigurations such as overly permissive access, privileged containers, missing encryption, and unsafe network exposure.

Reporting

HTML (dark theme, charts, filters, detailed cards)
SARIF 2.1.0 (for SARIF-aware dashboards and IDEs)
JSON (CI/CD, SIEM, automation)
Markdown (PRs, wikis, documentation)

Engine & Architecture

Rule engine abstraction (regex, AST, taint, semantic).
Rule indexing and keyword-based search for large rule sets.
Plugin system for modules (SAST, Secrets, SCA, DAST, Nuclei, IaC).
Scan orchestrator to coordinate multi-module runs.
Scan history database, diff mode, suppression, and performance metrics.

Installation

From the project root:

pip install .

Or run without installing:

python -m codebuster <target>
python codebuster/cli.py <target>

Requirements

Python 3.8 or higher.
Core dependencies are installed with the package (requests, lxml, beautifulsoup4, pyyaml, tqdm, colorama, regex).

Optional extras

pip install .[async]    # aiohttp — faster DAST scanning
pip install .[ast]      # tree-sitter — deeper AST analysis
pip install .[all]      # async + ast

Quick Start

Codebuster chooses modules from your targets:

Target	Default modules
File or directory	SAST, Secrets, SCA
URL	DAST, Nuclei
Paths + URLs	All applicable

codebuster app.py                          # File → SAST + Secrets + SCA
codebuster ./myproject                     # Directory → SAST + Secrets + SCA
codebuster http://localhost:8080           # URL → DAST + Nuclei
codebuster ./src http://localhost:8080     # Both → all modules

Command-Line Reference

Positional arguments

Argument	Description
`targets`	Files, directories, or URLs to scan (multiple allowed).

Scan technique flags (Nmap-style)

Flag	Description
`-sS`, `--sast`	SAST only.
`-sC`, `--secrets`	Secrets only.
`-sD`, `--sca`	SCA only.
`-sW`, `--dast`	DAST only (requires URL).
`-sN`, `--nuclei`	Nuclei only (requires URL).
`-sI`, `--iac`	IaC only.
`-sA`, `--all`	All applicable modules.
`-A`, `--aggressive`	All modules + verbosity 2.

Timing (`-T`)

Level	Name	Pages	Timeout
1	Sneaky	10	15s
2	Polite	25	10s
3	Normal (default)	50	8s
4	Aggressive	100	5s
5	Insane	200	3s

Output

Flag	Description
`-oH`, `--output-html FILE`	HTML report.
`-oJ`, `--output-json FILE`	JSON report.
`-oS`, `--output-sarif FILE`	SARIF 2.1.0 report.
`-oN`, `--output-markdown FILE`	Markdown report.
`-oA`, `--output-all BASE`	All formats: `BASE.html`, `BASE.json`, `BASE.sarif`.

Filtering

Flag	Description
`--min-severity LEVEL`	Minimum severity (CRITICAL, HIGH, MEDIUM, LOW, INFO). Default: LOW.
`--fail-on LEVEL`	Exit with code 1 if any finding ≥ this severity (for CI).
`--exclude MODULE`	Skip modules (e.g. SAST, DAST, SCA, Secrets, Nuclei).

General

Flag	Description
`--max-size KB`	Max file size to scan (default 300 KB).
`--no-banner`	Suppress banner.
`--no-color`	Disable colored output.
`-v`, `--verbosity`	Increase verbosity (repeat for more).
`--version`	Show version and exit.
`--list-rules`	List SAST/Secrets rules and exit.
`--list-scripts`	List Nuclei script categories and exit.

SAST / deep scanning

Flag	Description
`--deep`	Enable deep taint analysis.
`--show-taint-paths`	Show full taint propagation paths.
`-j`, `--jobs N`	Parallel SAST jobs (0 = auto).

Configuration

Flag	Description
`--config FILE`	Config file (YAML or JSON).
`--custom-rules DIR`	Directory of custom rules (YAML/JSON).

DAST

Flag	Description
`--rate-limit N`	Requests per second (0 = no limit).
`--user-agent STRING`	Custom User-Agent.
`--proxy URL`	Proxy (e.g. `http://proxy:8080`).
`--auth-type TYPE`	basic, bearer, apikey.
`--auth-user`, `--auth-pass`, `--auth-token`	Auth credentials.
`--passive`	Passive DAST only (no active tests).

Nuclei

Flag	Description
`--script CATEGORY`	vuln, discovery, auth, safe, intrusive, all.
`--script-args TAGS`	Comma-separated tags (e.g. `cve,rce,sqli`).

Secrets

Flag	Description
`--no-git`	Skip Git history scanning.

Rules management

Use the rules subcommand:

codebuster rules list              # List rule packs and counts
codebuster rules validate          # Validate YAML/JSON rule packs
codebuster rules update            # Update rule packs (if supported)
codebuster rules update-sca        # Update SCA CVE database

Examples

Scan techniques

codebuster -sS ./src                  # SAST only
codebuster -sC ./src                  # Secrets only
codebuster -sD .                      # SCA only
codebuster -sW http://target.com      # DAST only
codebuster -sN http://target.com      # Nuclei only
codebuster -sI ./terraform            # IaC only
codebuster -sA ./src                  # All applicable
codebuster -A ./src                   # All + verbose

Output and filtering

codebuster ./src -oH report.html
codebuster ./src -oJ report.json -oS results.sarif
codebuster ./src -oA scan_results
codebuster ./src --min-severity HIGH
codebuster ./src --fail-on CRITICAL

Deep SAST and parallelism

codebuster ./src --deep --show-taint-paths
codebuster ./src -j 4
codebuster ./src -j 0                 # Auto-detect CPU cores

DAST with auth and proxy

codebuster -sW --auth-type basic --auth-user admin --auth-pass secret http://target.com
codebuster -sW --auth-type bearer --auth-token TOKEN http://target.com
codebuster -sW --proxy http://proxy:8080 --rate-limit 5 http://target.com

Nuclei by category/tags

codebuster -sN --script vuln http://target.com
codebuster -sN --script-args cve,rce,sqli http://target.com

Config and custom rules

codebuster ./src --config ~/.codebuster/config.yaml
codebuster ./src --custom-rules ./rules

Configuration

Config files are optional. Precedence (highest first):

CLI arguments
Project config: .codebuster.yaml or .codebuster.json in project root
User config: ~/.codebuster/config.yaml or ~/.codebuster/config.json
Defaults

Example ~/.codebuster/config.yaml

rules:
  custom_rules_dir: "~/.codebuster/rules"
  severity_overrides:
    SQL001: "CRITICAL"
  disabled_rules:
    - "SQL002"

scanning:
  max_file_size_kb: 300
  parallel_jobs: 0      # 0 = auto
  deep_analysis: false

dast:
  rate_limit: 10
  user_agent: "Codebuster/2.0.0"
  proxy: "http://proxy:8080"
  auth:
    type: "basic"
    username: "user"
    password: "pass"

suppression:
  file: "~/.codebuster/suppressions.yaml"
  enabled: true

history:
  database: "~/.codebuster/history.db"
  enabled: true

Custom Rules

Custom SAST rules are YAML or JSON. Place them in a directory and pass it with --custom-rules (or set rules.custom_rules_dir in config).

Example custom_sast.yaml

rules:
  - id: "CUSTOM001"
    title: "Custom vulnerability pattern"
    sev: "HIGH"
    cwe: "CWE-XXX"
    owasp: "A03:2021-Injection"
    desc: "Description of the vulnerability."
    fix: "How to fix it."
    langs: ["python", "javascript"]
    pattern: "dangerous_function\\(.*\\)"

Secret patterns: use files named *secret*.yaml or *secret*.json in the custom rules directory.

Bundled rule packs live under rules/ in the repo:

SAST: rules/sast/*.yaml — load with --custom-rules rules (or point to the repo rules folder).
Secrets: rules/secrets/*.yaml
DAST: rules/dast/*.yaml (passive, active, headers, paths) — loaded from current working directory when present.
Nuclei: rules/nuclei/*.yaml — loaded from current working directory when present.

Suppression

Use a suppression file to hide known false positives (enable via config or a future --suppress flag). Example format:

suppressions:
  - id: "SQL001"
    reason: "False positive - using parameterized queries"
    file: "app/db.py"
    line: 42

  - pattern:
      rule_id: "SEC001"
      file_pattern: "**/test_*.py"
    reason: "Test files contain example secrets"

CI/CD

Use --fail-on to fail the pipeline when findings meet a severity threshold:

codebuster ./src -oS results.sarif --fail-on HIGH
# Then upload results.sarif (e.g. GitHub Code Scanning, upload-sarif action)

Exit codes

Code	Meaning
0	Scan finished; no failure threshold exceeded.
1	At least one finding ≥ `--fail-on` severity, or an error occurred.

Example (GitHub Actions)

- name: Run Codebuster
  run: |
    pip install .
    codebuster ./src -oS results.sarif --fail-on HIGH
- name: Upload SARIF
  uses: github/codeql-action/upload-sarif@v2
  with:
    sarif_file: results.sarif

Severity Levels

Severity	Use
CRITICAL	RCE, SQL injection, hardcoded secrets — act immediately.
HIGH	Command injection, path traversal, serious misconfigs.
MEDIUM	Weak crypto, missing headers, moderate risk.
LOW	Information disclosure, minor issues.
INFO	Best-practice and informational.

Supported Languages & Manifests

SAST: Python, JavaScript, TypeScript, Java, Go, PHP, Ruby, C, C++, C#, Rust, Kotlin, Swift, Shell, YAML, Terraform, and more.

SCA manifests: requirements.txt, Pipfile.lock, pyproject.toml, package.json, package-lock.json, yarn.lock, pom.xml, go.mod, Gemfile.lock, Cargo.lock, composer.lock.

Environment Variables

Variable	Description
`HTTP_PROXY`, `HTTPS_PROXY`	Proxy for DAST/HTTP requests.
`CODEBUSTER_HISTORY_DB`	Path to scan history database.
`NO_COLOR`	Disable colored output (same as `--no-color`).

Troubleshooting

Colors on Windows
Install colorama or use --no-color.

Unicode errors
Use --no-color or set PYTHONIOENCODING=utf-8.

Slow scans
Use -j 0 for parallel SAST; use -T5 for faster DAST where appropriate; use --exclude to skip modules.

False positives
Use suppression file, --min-severity, or disable specific rules in config.

Optional dependencies
For best experience:

pip install requests lxml beautifulsoup4 pyyaml tqdm colorama regex

For faster DAST: pip install aiohttp.
For deeper AST: pip install tree-sitter tree-sitter-python tree-sitter-javascript.

Git history
If Git scanning fails, ensure the target is a Git repo and git is on PATH, or use --no-git.

DAST/Nuclei
These modules send real HTTP requests. Only scan systems you own or have explicit permission to test.

Legal Notice

SAST, Secrets, SCA, IaC: Only read local files — safe to run on your code and configs.
DAST and Nuclei: Perform live HTTP requests. Only scan systems you own or have explicit written permission to test. Unauthorized scanning may violate computer misuse laws in your jurisdiction.

File Structure (after setup)

Typical paths:

~/.codebuster/config.yaml — user config
~/.codebuster/history.db — scan history (if enabled)
~/.codebuster/suppressions.yaml — suppression rules
~/.codebuster/rules/ — custom rules directory

Repo layout:

codebuster/ — main package (cli.py, cb_sast.py, cb_secrets.py, cb_sca.py, cb_dast.py, cb_nuclei.py, cb_iac.py, cb_engine.py, cb_core.py, etc.)
rules/ — bundled rule packs (sast, secrets, dast, nuclei)
tools/ — utilities (e.g. ingest_semgrep, validate_rules, export_rules)

Quick Reference

Command	Description
`codebuster app.py`	Scan a file (auto modules).
`codebuster ./project`	Scan directory (auto).
`codebuster http://localhost`	Web scan (auto).
`codebuster ./src http://localhost`	Full scan (paths + URL).
`codebuster -sS ./src`	SAST only.
`codebuster -sC ./src`	Secrets only.
`codebuster -sD .`	SCA only.
`codebuster -sW URL`	DAST only.
`codebuster -sN URL`	Nuclei only.
`codebuster -sA ./src`	All applicable.
`codebuster -oA scan`	All report formats.
`codebuster --fail-on CRITICAL`	CI gate.
`codebuster --help`	Full help.
`codebuster --version`	Version info.

For full option details, run:

codebuster --help

Name		Name	Last commit message	Last commit date
Latest commit History 2 Commits
codebuster		codebuster
rules		rules
tools		tools
CODEBUSTER_COMPLETE_REFERENCE.txt		CODEBUSTER_COMPLETE_REFERENCE.txt
CODEBUSTER_GUIDE.txt		CODEBUSTER_GUIDE.txt
README.md		README.md
SCALING_COMMANDS.txt		SCALING_COMMANDS.txt
cli_output.txt		cli_output.txt
full_output.txt		full_output.txt
git		git

Folders and files

Latest commit

History

Repository files navigation

Codebuster — Unified Offline Security Scanner

Features

Unified CLI

SAST

Secrets

SCA

DAST

Nuclei-style Scanner

IaC

Reporting

Engine & Architecture

Installation

Quick Start

Command-Line Reference

Positional arguments

Scan technique flags (Nmap-style)

Timing (-T)

Output

Filtering

General

SAST / deep scanning

Configuration

DAST

Nuclei

Secrets

Rules management

Examples

Configuration

Custom Rules

Suppression

CI/CD

Severity Levels

Supported Languages & Manifests

Environment Variables

Troubleshooting

Legal Notice

File Structure (after setup)

Quick Reference

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Timing (`-T`)

Packages