Argus

Your open-source AI Security Engineer. Point it at a codebase or a running app. It maps the system, runs layered security analysis, explains every finding the way a senior application-security engineer would, and where it can, it writes the fix and checks that the fix actually works.

Install · Quick start · How it works · Docs · Roadmap

Argus is not just another scanner that prints a list. For each finding it tells you why it is a vulnerability, how an attacker would exploit it, the business impact, the likelihood and severity, the CWE and OWASP mapping, and concrete remediation. Then it can generate a patch and confirm the patch closes the issue.

Status: early alpha. The architecture and full pipeline are in place: a working CLI, eight built-in scanners (including a first-class LLM/agent scanner), a multi-provider AI layer, cross-file taint analysis, and six report formats. See the roadmap.

Why Argus

Install

# From PyPI
pip install argus-appsec

# With cloud model support
pip install "argus-appsec[anthropic,openai]"

# With the AST data-flow tier (deeper Python/JS taint analysis, via tree-sitter)
pip install "argus-appsec[ast]"

# With the optional web dashboard (scan history and risk trends)
pip install "argus-appsec[dashboard]"

From source, for development:

git clone https://github.com/hasipfaruk/Argus
cd Argus
pip install -e ".[dev]"

Requires Python 3.10+. The installed command is argus.

Quick start

# Scan a local project and print a table
argus scan ./my-app

# Turn on the flagship features and write an HTML report
argus scan ./my-app --attack-sim --patches -f html -o report.html

# Scan a remote repository (shallow-cloned to a temp dir, then cleaned up)
argus scan https://github.com/org/repo

# Apply Argus's verified fixes to a branch and open a pull request
argus fix ./my-app --open-pr

# Use a local model so code stays on your machine
argus scan ./my-app --ai-provider ollama --ai-model llama3.1

# Machine-readable output for CI, failing the build on High and above
argus scan ./my-app -f sarif -o results.sarif --fail-on high

Explore what is available:

argus scanners     # list scanners
argus reporters    # list report formats
argus providers    # list AI providers and whether each is usable right now
argus init         # write a starter .argus.yml

CI in one block

The official GitHub Action uploads findings to GitHub Code Scanning and is diff-aware on pull requests, so merges are gated only on findings a PR introduces, never on pre-existing ones:

permissions:
  contents: read
  security-events: write
steps:
  - uses: actions/checkout@v4
    with: { fetch-depth: 0 }
  - uses: hasipfaruk/Argus@v0.7.0
    with:
      fail-on: high

You also get pre-commit hooks that block secrets before they enter git history, an official Docker image (ghcr.io/hasipfaruk/argus), and GitLab CI and Bitbucket Pipelines snippets. See docs/ci-cd.md.

How it works

 target  -->  resolve   -->  analyze    -->  scan      -->  enrich     -->  report
             path/git/     languages,     secrets,       reasoning,      json, sarif,
             url           frameworks,    deps, sast,     attack sim,     gitlab, md,
                           architecture   iac, llm        patches         html, csv

The engine never modifies the target. It returns a ScanResult, and its only write is to Argus's own cache (--no-cache disables even that). Scanners run concurrently and unchanged files reuse cached findings, so warm scans stay fast (measured numbers) while reports stay deterministic, byte for byte. Reporting and any pull-request creation are separate, explicit steps. See docs/architecture.md.

Configuration

Drop a .argus.yml in your project root (generate one with argus init):

min_severity: low
fail_on: high
attack_simulation: true
generate_patches: true
ai:
  provider: ollama      # heuristic | anthropic | openai | ollama
  model: llama3.1
scanner_options:
  secrets:
    entropy_threshold: 4.2

Full reference: docs/configuration.md.

Extending Argus

Everything is a plugin. Here is a whole scanner:

from argus.core.plugin import Scanner, ScannerContext, scanner
from argus.core.models import Finding, Location, Severity

@scanner
class HelloScanner(Scanner):
    name = "hello"
    category = "example"
    description = "Flags TODO comments as a demo."

    def scan(self, ctx: ScannerContext):
        for f in ctx.project.files():
            for i, line in enumerate(f.lines(), 1):
                if "TODO" in line:
                    yield Finding(
                        id=f"hello:todo:{i}", rule_id="hello.todo", scanner=self.name,
                        title="TODO left in code", description="A TODO marker.",
                        location=Location(path=f.rel_path, start_line=i),
                        severity=Severity.INFO,
                    )

Register it via the argus.plugins entry point in your package and Argus picks it up automatically. Prefer regex over code? You can add a rule in plain YAML instead. Full guide: docs/plugins.md.

AI providers and data handling

If a requested provider is unavailable, Argus warns and falls back to heuristic so a scan always completes.

Fixing, not just finding

argus fix closes the loop. It scans a repository, applies the fixes it can verify locally to a fresh branch, commits them, and with --open-pr opens a pull request.

argus fix ./my-app --dry-run      # preview the changes, write nothing
argus fix ./my-app                # apply fixes to a branch and commit locally
argus fix ./my-app --open-pr      # also push and open a PR (needs GITHUB_TOKEN)

Only deterministic, self-verified fixes are applied by default. Examples: unsafe yaml.load becomes yaml.safe_load, weak hashes become SHA-256, shell=True is removed, debug=True becomes debug=False, and torch.load gains weights_only=True. See docs/fixing.md.

Roadmap

Implemented. Project analysis; secrets, dependency, SAST, and IaC scanners; a first-class LLM and agent security scanner (OWASP LLM Top 10); live OSV vulnerability data; multi-provider AI enrichment; Attack Simulation Mode; deterministic patch generation with self-verification; automated fix branches and pull requests (argus fix); baseline and diff-aware scanning; dependency reachability analysis; opt-in secret verification; safe runtime posture checks for a live URL; per-file caching and parallel scanners; and JSON, SARIF, GitLab, Markdown, HTML, and CSV reporting.

Deep code analysis. AST data-flow scanning ships for Python and JavaScript/TypeScript (pip install "argus-appsec[ast]"), tree-sitter taint analysis that follows untrusted input through multiple hops into a sink and treats parameterized queries and sanitized values as safe. For Python it also includes a cross-file, inter-procedural tier that follows taint one hop across a function and file boundary. Go ships SAST rules today, with more languages next.

Author rules in YAML. Add SAST rules with only regex and a few fields, no Python, via .argus/rules/*.yml or scanner_options.patterns.rules. See docs/plugins.md.

Web dashboard. Scan history and risk trends ship as an optional extra: pip install "argus-appsec[dashboard]" then argus dashboard. See docs/dashboard.md.

Distribution. An official GitHub Action, pre-commit hooks, and a published Docker image. See docs/ci-cd.md.

Planned. Full dynamic analysis (DAST) building on the posture layer, deeper taint depth (multi-hop cross-file), more deep-analysis languages, team collaboration on the dashboard, and richer compliance rule packs.

Known limitations

Argus is early-stage and honest about what it does not yet do, because a security scanner you cannot trust is worse than none:

• Primarily static analysis. It reads code rather than running your app. The --live-target posture layer adds safe, read-only runtime checks (headers, cookies, TLS, exposed paths), but it is not full DAST. There is no crawling, fuzzing, or exploitation.
• Deepest for Python and JavaScript/TypeScript. Other languages are detected and covered by the secrets, dependency, LLM, and IaC scanners, and Go has SAST rules, but code-level coverage for the rest is limited so far.
• Code scanning has blind spots. The default regex tier catches common patterns. The optional AST tier follows multi-hop and one-hop cross-file data flows and avoids common false positives, but deeper multi-hop cross-file flows can still be missed. Treat a clean result as "no known issues found," not a proof of safety.
• Dependency coverage depends on OSV. Offline, it falls back to a small bundled advisory seed (PyPI and npm) and tells you so.

Treat Argus as a strong, fast first line of defense, not a replacement for a manual security review of critical code.

Contributing

Contributions are welcome from everyone. The flow is the standard one:

1. Fork this repository.
2. Create a branch and make your change, with tests.
3. Open a pull request. The template will guide you, and CI runs tests and lint automatically.

Scanners, language support, compliance rules, and report formats are especially welcome, and the plugin model means most additions never touch the core. See CONTRIBUTING.md for setup and standards, and CODE_OF_CONDUCT.md for community guidelines.

License

Apache-2.0. See LICENSE.