argus-ffi 1.1.0

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.

---

Core Capabilities

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

---

Installation

Prerequisites: Rust toolchain (rustup).

Build from source

git clone https://github.com/SSL-ACTX/argus.git
cd argus
cargo build --release

# Run the binary
./target/release/argus --help

Install globally

cargo install --path .

---

Usage

At minimum, provide one or more targets (-t) and choose a scanning mode (--entropy or -k).

argus -t <path_or_url> [OPTIONS]

Personas (quiet vs debug)

argus ships with two output personas that control noise, story collapsing, and request-trace verbosity:

• Scan (quiet/CI-safe): --mode scan or --quiet (default)
  • Collapses low-confidence and doc-context stories.
  • Suppresses request-trace details in terminal output.
• Debug (loud): --mode debug or --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.

Common workflows

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

2. 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.ndjson

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

5. Quiet CI Scan (Noise-Reduced)

argus -t . -k "token" --deep-scan --flow-scan --request-trace --quiet --confidence-floor 4

---

Output Modes

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

---

Python / PyO3 FFI

argus exposes a PyO3-friendly FFI module behind the python-ffi feature.

PYO3_USE_ABI3_FORWARD_COMPATIBILITY=1 cargo build --release --features python-ffi

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

Maturin (recommended for easy import)

pip install maturin
maturin develop --release

Then:

import argus_ffi

Python tests

pip install -e ".[test]"
pytest python/tests

Release to PyPI

Push a version tag (e.g., v1.1.0) to trigger the publish workflow:

git tag v1.1.0
git push origin v1.1.0

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

---

WASM Support

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

The module exports scan_bytes_json(bytes, options) and scan_bytes_count(bytes, options).

---

Deep Analysis and Security Heuristics

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:

🔍 Context & Provenance

• 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!
• 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).

🧬 Structural Heuristics

• 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 & Auth Logic

• Protocol Drift: Flags insecure protocol downgrades near sensitive data (e.g., switching from https:// to http:// 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., DELETE or POST implies 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, token in response handlers).

⚠️ Review Hints

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

---

Traffic Analysis & Attack Surface

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)
• Obfuscation Detection: Flags signatures of minified or packed code (e.g., hex-encoded strings, massive one-liners) often used to hide malicious logic.

---

Risk Visualization

When running in human-readable mode, argus provides high-level summaries to help prioritization.

Risk Heatmap

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

Flow Context Graph

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

---

Smart Suppression

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.

---

Advanced Configuration

Control Flow Analysis (--flow-scan)

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.

Optional Features

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.

---

Options Reference

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.

---

License

This project is licensed under the AGPL-3.0 License. See LICENSE for details.

---