Skip to content

Home

Argus - Perception is Protection

Learn more at argus.huntridgelabs.com


GitHub Release Unit Tests Integration Tests codecov

License: AGPL v3 AICaC


Unified security scanning — SAST, containers, IaC, secrets, and DAST from a single CLI or GitHub Actions workflow.

Table of Contents

Quick Start

The argus Python SDK is the primary interface for running security scans. It works locally, in CI, and on any platform with Python 3.11+.

pip install argus-security

# Initialize config and scan
argus init
argus scan

Or scan immediately without a config file:

argus scan bandit gitleaks osv --severity-threshold high

Interactive triage

After a scan, argus view terminal opens a terminal UI for navigating findings — filter by severity, product, or scanner; search by CVE; drill into details; export to CSV / JSON / Markdown / SARIF; see an executive dashboard. Ships behind an optional extra:

pip install 'argus-security[terminal]'
argus view terminal                         # load ./argus-results/argus-results.json
argus scan --interface=terminal             # scan, then drop straight into the terminal viewer

Full keyboard reference and workflow in docs/view-terminal.md.

GitHub Actions (Composite Actions)

For GitHub Actions users, composite actions remain available for direct integration:

name: Security Scan
on: [pull_request, push]

permissions:
  contents: read
  security-events: write
  pull-requests: write

jobs:
  sast:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6

      - uses: huntridge-labs/argus/.github/actions/scanner-gitleaks@1.1.0
        with:
          enable_code_security: true
          fail_on_severity: high
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

      - uses: huntridge-labs/argus/.github/actions/scanner-bandit@1.1.0
        with:
          enable_code_security: true
          fail_on_severity: high

Supported Scanners

Category Scanner Description
SAST CodeQL GitHub semantic code analysis
Gitleaks Secret detection in git history
Bandit Python security linter
OpenGrep Fast multi-language static analysis
Container Trivy Container Comprehensive vulnerability scanner
Grype Fast, accurate CVE detection
Syft Software Bill of Materials (SBOM)
Exposed-port surface Reports declared Dockerfile EXPOSE ports as findings (MEDIUM for risky-defaults watchlist: SSH, MySQL, Redis, etc.)
Infrastructure Trivy IaC Infrastructure as Code scanner
Checkov Policy as Code for cloud configs
Malware ClamAV Open-source antivirus engine
DAST ZAP Dynamic testing of running web/API endpoints (opt-in)

For detailed scanner configuration, see Scanner Reference.

Features

  • Argus SDK - Run scanners locally or in CI with argus scan
  • Unified interface - One CLI or workflow for all scanners
  • Flexible scanner selection - Use scanner groups or specific scanners
  • Interactive triage TUI - argus view terminal — keyboard-driven findings explorer with executive dashboard
  • SBOM input - argus scan --sbom path/to/sbom.json accepts CycloneDX / SPDX / Syft SBOMs (file or directory of SBOMs)
  • GitHub Security tab integration - Upload SARIF results to Code Scanning
  • PR comments - Inline feedback on pull requests
  • Severity-based failure control - Set thresholds for workflow failures
  • Container configuration - Scan multiple containers from a single config file
  • Matrix execution - Parallel scanning for multiple targets
  • Credential handling - Secrets stay out of argus.yml: name an env var via <field>_env, pipe via --registry-password-stdin, or both. Validator warns on literal vendor-shaped values; resolved values never reach logs / audit trail.
  • Supply-chain verification - Cosign-verify on every argus-owned image pull (Sigstore keyless), implicit @sha256: digest verification on every third-party image. Failure aborts the scanner.
  • Shell tab-completion - argus completion zsh >> ~/.zshrc (or bash) — Tab-completes subcommands, scanner / linter names, common flags. Auto-refreshes from the live scanner registry.
  • Optional AI summary - Generate executive security summaries from scan results using your own AI provider and API key (Copilot, Claude, or Gemini)
  • Interactive findings TUI - argus view terminal — keyboard-driven triage browser (pip install 'argus-security[terminal]')
  • Local web UI - argus view browser — localhost dashboard for non-engineer stakeholders (pip install 'argus-security[browser]')

GitHub Enterprise Server (GHES)

GHES users can use the argus SDK or composite actions directly from github.com - no mirroring required.

Architecture: Scanner logic lives in the argus Python SDK and in composite actions. The SDK is the primary interface; composite actions provide GitHub Actions integration.

GHES Quick Start 
name: Security Scan (GHES)

on: [pull_request, push]

permissions:
  contents: read
  security-events: write
  pull-requests: write

jobs:
  sast:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6

      # Use composite actions directly from github.com
      - uses: huntridge-labs/argus/.github/actions/scanner-gitleaks@1.1.0
        with:
          enable_code_security: true
          fail_on_severity: high
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          GITLEAKS_LICENSE: ${{ secrets.GITLEAKS_LICENSE }}

      - uses: huntridge-labs/argus/.github/actions/scanner-bandit@1.1.0
        with:
          enable_code_security: true
          fail_on_severity: high

See examples/github-enterprise/ for complete GHES workflow templates: - SAST Scanning - Container Scanning - Infrastructure Scanning - DAST Scanning

Documentation

Full documentation: huntridge-labs.github.io/argus

User Guides

Developer Docs

Usage Examples

SDK: Full Scan with Config File 
# argus.yml
scanners:
  - gitleaks
  - bandit
  - opengrep
  - osv
  - trivy-iac
  - checkov

scan_path: "."
severity_threshold: high

argus scan --config argus.yml
SDK: SAST Scanners Only 
argus scan bandit opengrep gitleaks --severity-threshold medium
SDK: Container Scanning 
argus scan container --severity-threshold critical
SDK: Infrastructure as Code 
# argus.yml
scanners:
  - trivy-iac
  - checkov

scan_path: "terraform/"
severity_threshold: high

argus scan --config argus.yml
GitHub Actions: Composite Actions 
name: Security Scan

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

permissions:
  contents: read
  security-events: write
  pull-requests: write

jobs:
  sast:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6

      - uses: huntridge-labs/argus/.github/actions/scanner-gitleaks@1.1.0
        with:
          enable_code_security: true
          fail_on_severity: high
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

      - uses: huntridge-labs/argus/.github/actions/scanner-bandit@1.1.0
        with:
          enable_code_security: true
          fail_on_severity: high
GitHub Actions: Config-Driven Container Scanning See [Container Scanning Guide](guides/container-scanning.md) for complete documentation.

Configuration

SDK Configuration (argus.yml)

scanners:
  - gitleaks
  - bandit
  - osv
  - trivy-iac

scan_path: "."
severity_threshold: high

CLI Scanner Selection

# Specific scanners
argus scan gitleaks bandit osv

# With severity threshold
argus scan --severity-threshold high

# With config file
argus scan --config argus.yml

Severity levels: none, low, medium, high, critical

See Failure Control Guide for detailed threshold configuration.

GitHub Actions Permissions

When using composite actions in GitHub Actions workflows:

permissions:
  contents: read           # Read repository content
  security-events: write   # Upload to GitHub Security tab
  pull-requests: write     # Post PR comments
  actions: read           # Read Actions artifacts

Secrets

Scanner-specific secrets (for GitHub Actions composite action usage):

Secret Required For Description
GITLEAKS_LICENSE Gitleaks (organizations) License from gitleaks.io
GITHUB_TOKEN PR comments, Security tab Automatically provided
Registry secrets Private containers Token for authentication

MCP Server (AI Integration)

Argus includes an MCP server for AI-assistant integration. Tools like Claude Desktop, Claude Code, Cursor, Continue, and Cline can run scans, validate configs, classify IaC changes, and explain findings — without leaving the chat.

Zero-install (recommended for AI-tool-only users — no global Python install needed):

uvx --from 'argus-security[mcp]' argus mcp

Or install via pip (recommended if you also use the Argus CLI):

pip install 'argus-security[mcp]'

Add to your AI tool's MCP configuration:

{
  "mcpServers": {
    "argus": {"command": "argus", "args": ["mcp"]}
  }
}

Available tools: argus_scan, argus_detect, argus_validate, argus_list_scanners, argus_init, argus_classify, argus_explain_finding, argus_scan_summary. Resources: argus://config, argus://results/latest, argus://config/schema. Prompts: security_review, fix_findings, setup_scanning.

See docs/mcp.md for per-client config (Claude Desktop, Claude Code, Cursor, Continue, Cline), the full tool reference, and the list of MCP server registries where Argus is listed for discovery.

Contributing

Contributions welcome! See CONTRIBUTING.md for guidelines.

Development Setup

Quick Start with Dev Container (Recommended):

Open in Dev Containers

  1. Install VS Code + Dev Containers extension
  2. Open repository → "Reopen in Container"
  3. All dependencies ready! Run npm test
# Install dependencies
npm install
pip install -r .devcontainer/requirements.txt

# Run tests
npm test

# See tests/CONTRIBUTING.md for detailed testing guide

License

AGPL v3 License - see LICENSE.md for details.

Support