Skip to content

Home

Argus - Perception is Protection


GitHub Release Unit Tests Integration Tests codecov

License: AGPL v3 AICaC


Unified security scanning for GitHub Actions — SAST, containers, IaC, secrets, and DAST in a single workflow.

Table of Contents

Quick Start

Create .github/workflows/security.yml:

name: Security Scan
on: [pull_request, push]

jobs:
  security:
    uses: huntridge-labs/argus/.github/workflows/reusable-security-hardening.yml@0.6.7
    with:
      scanners: all
      enable_code_security: true
      post_pr_comment: true
      fail_on_severity: high
    secrets: inherit

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)
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

  • Unified interface - One workflow for all scanners
  • Flexible scanner selection - Use all, scanner groups, or specific scanners
  • 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
  • Private registry support - Authenticate to container registries
  • Environment variable expansion - Dynamic configuration values

GitHub Enterprise Server (GHES)

GHES users can use our composite actions directly from github.com - no mirroring required.

Architecture: This project uses an actions-first architecture where all scanner logic lives in composite actions. The reusable workflows are thin wrappers for backwards compatibility on github.com.

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@0.6.7
        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@0.6.7
        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

All Scanners with GitHub Security 
name: Complete Security Scan

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
  schedule:
    - cron: '0 2 * * 1'  # Weekly Monday at 2 AM

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

jobs:
  security:
    uses: huntridge-labs/argus/.github/workflows/reusable-security-hardening.yml@0.6.7
    with:
      scanners: all
      enable_code_security: true
      post_pr_comment: true
      fail_on_severity: high
    secrets: inherit
SAST Scanners Only 
name: SAST Security Scan

on: [pull_request]

jobs:
  sast:
    uses: huntridge-labs/argus/.github/workflows/reusable-security-hardening.yml@0.6.7
    with:
      scanners: codeql,bandit,opengrep,gitleaks
      codeql_languages: 'python,javascript'
      enable_code_security: true
      fail_on_severity: medium
    secrets:
      GITLEAKS_LICENSE: ${{ secrets.GITLEAKS_LICENSE }}
Container Scanning 
name: Container Security

on:
  push:
    tags: ['v*']

jobs:
  scan-image:
    uses: huntridge-labs/argus/.github/workflows/reusable-security-hardening.yml@0.6.7
    with:
      scanners: trivy-container,grype,sbom
      image_ref: 'ghcr.io/myorg/myapp:${{ github.ref_name }}'
      enable_code_security: true
      fail_on_severity: critical
Config-Driven Multiple Containers 
name: Multi-Container Scan

on:
  push:
    paths: ['container-config.yml']

jobs:
  scan:
    uses: huntridge-labs/argus/.github/workflows/container-scan-from-config.yml@0.6.7
    with:
      config_file: container-config.yml
      enable_code_security: true
      fail_on_severity: high
    secrets: inherit
**container-config.yml:** 
containers:
  - name: frontend
    registry:
      host: ghcr.io
      username: ${GITHUB_TRIGGERING_ACTOR}
      auth_secret: GITHUB_TOKEN
    image:
      repository: myorg
      name: frontend
      tag: latest
    scanners:
      - trivy-container
      - grype

  - name: backend
    image: myorg/backend:latest
    scanners:
      - trivy-container
      - sbom
See [Container Scanning Guide](https://github.com/huntridge-labs/argus/blob/main/docs/container-scanning.md) for complete documentation.
Infrastructure as Code 
name: Infrastructure Security

on:
  pull_request:
    paths:
      - 'terraform/**'
      - 'infrastructure/**'

jobs:
  iac:
    uses: huntridge-labs/argus/.github/workflows/reusable-security-hardening.yml@0.6.7
    with:
      scanners: trivy-iac,checkov
      iac_path: 'terraform/'
      enable_code_security: true
      fail_on_severity: high
Branch-Specific Thresholds 
name: Security with Branch Rules

on:
  pull_request:
    branches: ['**']

jobs:
  security:
    uses: huntridge-labs/argus/.github/workflows/reusable-security-hardening.yml@0.6.7
    with:
      scanners: all
      enable_code_security: true
      post_pr_comment: true
      fail_on_severity: ${{ github.base_ref == 'main' && 'high' || 'critical' }}
    secrets: inherit

Configuration

Scanner Selection

  • All scanners: scanners: all
  • By category: scanners: sast, scanners: container, scanners: infrastructure
  • Specific scanners: scanners: codeql,trivy-container,gitleaks
  • Multiple categories: scanners: sast,container

Common Inputs

Input Description Default
scanners Scanners to run (comma-separated or category) Required
enable_code_security Upload SARIF to GitHub Security tab false
post_pr_comment Post findings as PR comments true
fail_on_severity Fail workflow on severity threshold none

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

See Failure Control Guide for detailed threshold configuration.

Permissions Required

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

Most secrets are optional and inherited via secrets: inherit. Scanner-specific secrets:

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

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

See .devcontainer/README.md for details.

  • Code of Conduct
  • Development setup
  • Pull request process
  • Commit message format

Development Setup

# 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