Learn more at argus.huntridgelabs.com

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

---

Table of Contents

• Quick Start
• Supported Scanners
• Features
• GitHub Enterprise Server (GHES)
• Documentation
• Usage Examples
• Configuration
• Contributing

Quick Start

Argus SDK (Recommended)

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.4.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.4.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.4.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.4.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

• Configuration Reference - Full argus.yml specification
• Scanner Reference - Complete configuration for all scanners
• Container Scanning - Config-driven matrix container scanning
• Failure Control - Severity-based workflow failure configuration
• Security Policy - Threat model, credential handling, supply-chain verification, vulnerability reporting
• Migration 0.6.x → 1.x - Side-by-side guide for upgrading consumer workflows
• Docker Troubleshooting - Runtime detection, bind-mount permissions, image pulls, proxies, and execution-failure signals

Developer Docs

• Contributing Guide - How to add scanners and actions
• Testing Guide - How to add and run tests
• Release Management - Release process and versioning
• Enhanced PR Comments - PR comment implementation

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.4.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.4.0
        with:
          enable_code_security: true
          fail_on_severity: high

GitHub Actions: Config-Driven Container Scanning

See Container Scanning Guide 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):

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

• Documentation: huntridge-labs.github.io/argus
• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Security: See SECURITY.md for vulnerability reporting