argus is a high-performance, multi-threaded security scanner designed to detect secrets, keys, and sensitive information in local files and remote URLs. It combines Shannon entropy analysis with fast multi-pattern matching to find both unknown and known secrets while minimizing false positives.
Unlike traditional regex scanners, argus builds a narrative ("Story") around every finding, analyzing control flow, variable types, and surrounding code topology to distinguish true risks from noise.
- Hybrid Detection Engine: Combines Aho-Corasick keyword search with Shannon Entropy analysis to catch both known patterns (API keys, tokens) and unknown random strings.
- Context-Aware Analysis: Uses heuristics to understand flow, scope, and variable relationships without requiring a heavy language server.
- Traffic Reconstruction: Traces HTTP requests (
fetch,axios,curl) to map your application's attack surface and API dependencies. - Adaptive Confidence: Scores every finding based on signals like variable naming, assignment distance, and file type (docs vs source).
- Git Integration: Optimized for CI/CD with diff-only scanning (
--diff) to flag secrets in new code.
Prerequisites: Rust toolchain (rustup).
git clone https://github.com/SSL-ACTX/argus.git
cd argus
cargo build --release
# Run the binary
./target/release/argus --helpcargo install --path .At minimum, provide one or more targets (-t) and choose a scanning mode (--entropy or -k).
argus -t <path_or_url> [OPTIONS]argus ships with two output personas that control noise, story collapsing, and request-trace verbosity:
- Scan (quiet/CI-safe):
--mode scanor--quiet(default)- Collapses low-confidence and doc-context stories.
- Suppresses request-trace details in terminal output.
- Debug (loud):
--mode debugor--loud- Expands story blocks and prints request-trace details.
You can override the minimum confidence shown with --confidence-floor <0-10> and expand repeated stories with --expand.
Key output controls
--mode scan|debug— select the output persona.--quiet/--loud— aliases for scan/debug personas.--confidence-floor <0-10>— drop findings below this confidence.--expand— expand repeated story blocks.
1. Enterprise Secret Scanning (High Precision) Scan a repository for high-entropy strings, identifying likely secrets while ignoring common false positives.
argus -t ./src --entropy --threshold 4.82. Targeted Keyword Audit Search for specific tokens or legacy keys in a remote file.
argus -t https://example.com/app.js -k API_KEY -k "Bearer "3. CI/CD Integration (Machine Readable) Output newline-delimited JSON for easy parsing by downstream tools.
argus -t . --entropy --json --output-format ndjson --output ./results.ndjson4. Full Security Audit (Deep Scan) Enable all heuristics, flow analysis, and request tracing for a comprehensive report.
argus -t . -k "token" --entropy --deep-scan --flow-scan --request-trace5. Quiet CI Scan (Noise-Reduced)
argus -t . -k "token" --deep-scan --flow-scan --request-trace --quiet --confidence-floor 4argus supports both human-readable terminal output and several machine-readable export modes.
- Human mode (default): prints a styled report to stdout.
- JSON to stdout: add
--json. - File outputs: set
--output <PATH>and choose--output-format:single(default): collect all findings and write one JSON file at the end.ndjson: stream one JSON object per line while scanning (best for big repos/CI).per-file: write one JSON file per scanned source into the output directory.story: write a grouped markdown report (Story Mode) to the output path.
argus exposes a PyO3-friendly FFI module behind the python-ffi feature.
PYO3_USE_ABI3_FORWARD_COMPATIBILITY=1 cargo build --release --features python-ffiThis produces a Python extension shared library in target/release/ (e.g., libargus.so on Linux). You can rename it to argus_ffi.so for import.
pip install maturin
maturin develop --releaseThen:
import argus_ffipip install argus-ffipip install -e ".[test]"
pytest python/testsPush a version tag (e.g., v1.1.0) to trigger the publish workflow:
git tag v1.1.0
git push origin v1.1.0Example (maturin-style usage):
from argus_ffi import ScanOptions, scan_json
opts = ScanOptions(
targets=["./src"],
keywords=["token"],
entropy=False,
deep_scan=True,
flow_scan=True,
request_trace=False,
mode="scan",
)
print(scan_json(opts))Build a WASM module with in-memory scanning (no filesystem access) using the wasm-ffi feature.
cargo build --target wasm32-unknown-unknown --release --no-default-features --features wasm-ffiThe module exports scan_bytes_json(bytes, options) and scan_bytes_count(bytes, options).
argus moves beyond simple pattern matching by applying a suite of heuristics to every potential match. When using --deep-scan, the following specific analysis modules are activated:
- Story Mode: Generates a natural language explanation for why a match is considered risky.
- Sink Provenance: Determines where the data flows. Detects if a secret is passed to:
- Network Sinks:
fetch,axios,send,open - Disk Sinks:
fs.write,File::create - Log Sinks:
console.log,println!
- Network Sinks:
- Leak Velocity: Estimates how quickly a secret might be exposed based on surrounding code (e.g., hardcoded in a public endpoint handler vs. buried in a config loader).
- Credential Shadowing: Detects when a placeholder (e.g.,
const KEY = "TODO") is "shadowed" or replaced by a real secret nearby, often indicating a committed production key. - Lateral Linkage: Identifies identical high-entropy tokens across valid source files, linking disparate parts of the codebase that share credentials.
- Secret Lineage: Traces the "origin" of a repeated secret to its most likely definition point.
- Surface Tension: Measures the complexity of the code surrounding a secret. High tension often correlates with critical logic rather than test data.
- Protocol Drift: Flags insecure protocol downgrades near sensitive data (e.g., switching from
https://tohttp://in the same scope). - Auth Drift: Detects HTTP requests that lack typical authentication headers (e.g.,
Authorization,X-API-Key) when surrounding requests use them. - API Capability Inference: Infers the risk level of an endpoint based on the method and context (e.g.,
DELETEorPOSTimplies destructive or state-changing capability). - Response Class Analysis: Guesses the sensitivity of the data returned by an endpoint based on variable naming (e.g.,
password,tokenin response handlers).
- Comment Escalation: Scans nearby comments for risk indicators (e.g., "TEMPORARY", "FIXME", "REMOVE THIS") that suggest technical debt or security shortcuts.
- Endpoint Morphing: Detects when a base URL is constructed dynamically in ways that obscure its destination (e.g., template literal injection).
With --request-trace, argus becomes a targeted DAST tool for source code.
- Request Tracing: Parses HTTP client calls (
fetch,axios,requests,curl) to reconstruct URLs and methods. - Attack Surface Mapping: Aggregates found URLs and classifies them:
- Public: Fully qualified domains (
https://api.stripe.com) - Localhost: Local development servers (
http://127.0.0.1:8080) - Internal: Private network IP ranges.
- Relative: API paths (
/api/v1/user)
- Public: Fully qualified domains (
- Obfuscation Detection: Flags signatures of minified or packed code (e.g., hex-encoded strings, massive one-liners) often used to hide malicious logic.
When running in human-readable mode, argus provides high-level summaries to help prioritization.
A weighted ranking of the most critical files based on match count, entropy scores, and heuristic signals.
🔥 Risk Heatmap (top files)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
1. src/config/secrets.ts — score 59.0 | hits 40 (entropy 38, keyword 2)
2. src/api/client.rs — score 44.5 | hits 30
With --flow-scan, argus prints a lightweight TUI tree showing the structural context of a finding.
Flow: [scope function:init L40 d12] [ctrl if L41] [assign d2] [chain window.open]
Context:
├─ scope: function init @L40:C15
├─ call: window.open
└─ ctrl: if @L41:C13
Reduce false positives without cluttering the output.
- Load Rules:
--suppress .argusignore - Generate Rules:
--suppress-out .argusignore(Appends new suppression candidates from the current scan) - Audit Rules:
--suppression-audit(Reports stale rules that no longer match anything or are too broad)
Rule Formats:
id:<variable_name>— Suppress by identifier (e.g.,id:example_key).<file>:<line>:<kind>— Suppress a specific match location.
In Deep Scan mode, argus will suggest Suppression Hints for findings that look like test data or examples, complete with a confidence score and a recommended "decay" date.
A lightweight, AST-free control flow analysis that works on most C-like languages. It provides:
- Scope: Current function/class/block.
- Control: Nearest
if,while,return. - Distance: How far the match is from assignments or returns.
Note
For JavaScript/TypeScript, flow analysis is heuristic by default. Enable the js-ast feature for precise AST-based parsing.
Compile argus with additional features for enhanced capabilities:
- JavaScript AST:
cargo build --features js-ast- Enables tree-sitter based parsing for JS/TS files.
- Syntax Highlighting:
cargo build --features highlighting- Enables true 24-bit syntax highlighting for code snippets in the terminal.
| Category | Flag | Description |
|---|---|---|
| Core | -t, --target <PATH> |
Target file, directory, or URL (repeatable). |
-k, --keyword <STR> |
Literal keyword to search for. | |
--entropy |
Enable Shannon entropy scanning. | |
--diff |
Scan only lines added in git diff. | |
| Output | --json |
Enable JSON output. |
--output <PATH> |
Output path or directory. | |
--output-format |
single (default), ndjson, per-file, or story. |
|
--no-color |
Disable ANSI colors. | |
| Tuning | --threshold <FLOAT> |
Entropy threshold (default: 4.5). |
-c, --context <N> |
Context window size in bytes (default: 80). | |
-j, --threads <N> |
Scan threads (default: auto). | |
--exclude <GLOB> |
Patterns to ignore (e.g. *.lock). |
|
| Analysis | --deep-scan |
Enable all heuristic analysis modules. |
--flow-scan |
Enable control-flow context. | |
--request-trace |
Enable HTTP traffic analysis. | |
| Manage | --suppress <PATH> |
Load suppression rules. |
--suppress-out |
Write new suppressions to file. |
This project is licensed under the AGPL-3.0 License. See LICENSE for details.
Author: Seuriin (SSL-ACTX)
v1.1.0