argus

Read-only host-compromise, patch-posture, and AI skill/MCP supply-chain scanner for macOS and Linux.

argus answers three questions in one command: is this machine compromised, is it missing a security-critical patch, and is an installed (or about-to-be-installed) AI agent skill or MCP server safe to trust. A deterministic Bash engine does the detection and writes a stable, machine-readable report; a human (or an AI agent through the bundled skill) triages it. It is safe to run on a developer or security engineer's own machine: it never changes anything without explicit consent, never executes a suspect artifact, and never phones home by default.

It was built for the October 2026 software supply-chain and credential-theft wave and is kept current, but the persistence, miner, patch-posture, and skill-audit checks are general-purpose.

• Why argus
• Quick start
• Install
• Usage
• The three lanes
• Skill and MCP audit
• Optional engines and consent-gated install
• Output and exit codes
• Safety contract
• Detection coverage
• Deep mode
• Accuracy and false positives
• Repository layout
• Limitations
• Contributing
• Security
• License

Most host scanners collapse distinct ideas into one number. argus keeps them separate, which is what makes its output trustworthy:

• Host state (am I compromised, do I hold a vulnerable build) is separate from a vulnerability's intrinsic severity (CVSS, CISA KEV). A vulnerable version installed is a loaded gun (latent); an active IOC, a live C2 connection, or a running miner is the gun firing (incident).
• A missing patch is a dated remediation obligation, not an incident, so it never pages an incident responder through the exit code.
• A regex match in a skill audit is evidence, never a clean bill of health. Context routing and unit-wide correlation decide the verdict, and prose intent is escalated to a semantic review.

git clone https://github.com/devx-commerce/argus.git ~/.claude/skills/argus

Then, in Claude Code, run the skill with /argus (or ask it to scan the machine). To run the engine directly:

cd ~/.claude/skills/argus
./scan.sh                 # host compromise + patch posture + installed skill/MCP audit
./scan.sh --audit PATH    # vet one untrusted skill/MCP (local path or git URL) before install

As a Claude Code skill (recommended):

git clone https://github.com/devx-commerce/argus.git ~/.claude/skills/argus

Standalone:

git clone https://github.com/devx-commerce/argus.git
cd argus && chmod +x scan.sh install-trivy.sh
./scan.sh

Requirements: bash (works with the macOS stock bash 3.2) and standard POSIX tools. Optional: lsof (present on macOS; falls back to ss on Linux), clamscan, trivy, git (for auditing a URL). No root is required; checks that need elevated access are recorded as skipped, not failed.

scan.sh                 default: host scan + patch posture + audit of installed skills/MCP
scan.sh --audit TARGET  audit ONE untrusted skill/MCP before install (local path or git URL)
scan.sh --no-audit      host scan only (skip the installed-skill/MCP audit)
scan.sh --install trivy consent-gated install of a pinned, checksum-verified engine, then use it
scan.sh --install clamav consent-gated install of ClamAV via the OS package manager
scan.sh --no-install    never prompt or install anything (also via ARGUS_NO_INSTALL for MDM)
scan.sh --trivy         use Trivy if already installed (CRITICAL findings only)
scan.sh --clamav        use ClamAV if already installed
scan.sh --root DIR      scan only DIR (filesystem layers only; for positive-control tests)
scan.sh --quiet         print only the summary; the full report is still written
scan.sh --no-color      disable ANSI color
scan.sh --help          usage

argus reports three independent lanes that must not be conflated:

1. Compromise - active-incident evidence (IOC match, persistence, a running miner, a live C2 connection, worm-written agent config). This lane alone drives the incident exit code.
2. Patch - dated remediation obligations (a vulnerable version is installed). Latent by design; excluded from the incident exit code. CISA KEV / actively-exploited items are flagged with their due date and rolled up in the summary.
3. Supply-chain - the skill/MCP audit verdict (advisory; never sets the host incident exit code).

A sibling project, akira-lite, reviews your own application code for bugs. argus deliberately does not do that: the skill/MCP audit is a trust decision about an untrusted third-party artifact, not a code review of your own code.

scan.sh --audit TARGET (and the default run, over every installed skill/MCP) vets an AI agent skill or MCP server for malicious intent and supply-chain trust: prompt injection, data exfiltration, persistence, excessive agency, remote-code fetch, MCP over-privilege, and known-bad indicators. Rules live in audit-rules.tsv and are a cheap pre-filter that only adds signal; a no-hit is never a clean bill. Context routing (prose vs code vs config) stops documenting a dangerous pattern from reading as performing it, findings are correlated across the whole unit, and the verdict is category-weighted, not a raw count. A git URL is validated and shallow-cloned with every transport, hook, and LFS filter disabled, and nothing in it is executed.

Per-unit verdicts:

A first-party allowlist (audit-allowlist.txt, full-path globs, optionally hash-pinned) keeps trusted skills from being condemned for their declared behavior. argus trusts almost nothing by default because trusting a skill by name is unsafe. Each operator adds their own reviewed entries.

argus is read-only. The only mutation it will make is installing a named security engine, and only with explicit consent. When Trivy or ClamAV is missing, argus offers to install it at the start of a run (so the check is thorough), never silently:

• Trivy: a pinned, checksum-verified single binary into a user-local directory. Harden the trust root with an out-of-band pin (ARGUS_TRIVY_SHA256 or trivy-pins.txt) or cosign; a same-origin checksum is the announced last-resort fallback.
• ClamAV: via the OS package manager (its own signing), user-level on macOS/Homebrew; on Linux it needs root, which argus never escalates to - it prints the exact command to run via admin/MDM. ClamAV 1.5+ verifies its signed virus database against a CA certificate store; argus detects that store, configures CVDCertsDirectory / --cvdcertsdir, and if verification still fails it prints the exact fix and continues without ClamAV rather than hanging or failing the scan.

CI, MDM, and --no-install (or ARGUS_NO_INSTALL) skip all prompts and installs.

The engine writes findings.tsv (tab-separated: epoch, severity, layer, category, title, evidence) and a human-readable report.txt to a temp directory, printed at the end. The summary leads with the action-bearing patch line, including a CISA KEV rollup with the nearest due date.

Exit codes are derived from the file, never from in-memory counters:

• 0 clean or info-only (host compromise lane)
• 1 any host HIGH
• 2 any host CRIT
• For --audit TARGET, an advisory space: 0 none, 10 CAUTION/INDETERMINATE, 20 DO_NOT_INSTALL/REMOVE.

Patch-posture and skill-audit findings never set the host incident exit code.

• Read-only on scan: never deletes, kills, quarantines, chmods. The only mutation is a consent-gated, pinned or package-manager-signed install of a named engine.
• Never executes a suspect or audited artifact. Suspect package versions are read from the filesystem; any Python it runs uses -I -S; a fetched URL is shallow-cloned with hooks and transports disabled and nothing in it is run.
• Never phones home by default. The only network actions are opt-in and announced (engine DB fetch, URL clone, consent-gated install).
• Redacts matched content to file:line, so it does not spill secrets from history or .env files into the report.
• Recommends; a human approves and acts.

1. IOC match - the tracked supply-chain wave from iocs.tsv (filenames, dist-info dirs, npm lockfile and node_modules versions, C2 addresses, wallet strings, malicious editor extensions).
2. Persistence - launchd / systemd / cron / rc files, pipe-to-shell droppers, authorized_keys changes, UID 0 accounts, third-party kexts, ld.so.preload.
3. Runtime - processes, sustained-CPU sampling, exec paths in temp dirs, miner process names, listening sockets, connections to mining-pool ports or IOC addresses, deleted-exe detection. Signals are correlation-weighted so a single weak match does not raise an alarm.
4. Package hygiene - unusual Python .pth startup hooks, editor-extension inventory.
5. Posture and optional engines - SIP/Gatekeeper, compromised-CA presence, optional ClamAV, optional Trivy (CRITICAL).
6. Patch posture - language runtimes, package managers, and VPN clients against current fixes, with CISA KEV flags and due dates. See PATCHES.md.
7. Agent-runtime persistence - hook/task commands in agent config (settings*.json, .vscode/tasks.json, .mcp.json) that carry an exec or egress primitive; registry hijacks; admin-added trusted root CAs.
8. Skill/MCP supply-chain audit - see above.

For ambiguous or numerous HIGH/CRIT findings, deep-mode.workflow.js fans out one read-only investigator per finding, each gathering context on the flagged file, process, or connection and returning a verdict, then a synthesis agent aggregates them. Investigators are restricted to read-only, treat audited content as untrusted data, and cannot downgrade a deterministic verdict.

argus is tuned for a very low false-positive rate on real developer and offensive-security machines. Lone common primitives (a single exec, a documented command, an install hook) stay informational; only correlated independent signals escalate a verdict. The loudest imperative (DO_NOT_INSTALL / REMOVE) is reserved for correlated malice so operators do not learn to override it. Detectors are validated with inert positive-control fixtures; a clean run alone cannot distinguish "clean" from "broken detector", so validate after editing rules.

scan.sh                  deterministic host engine (layers 1-8), summary, exit codes
skill-audit.sh           skill/MCP audit engine (sourced by scan.sh)
audit-rules.tsv          audit rule table (id, severity, scope, class, title, regex)
audit-allowlist.txt      first-party / operator-trusted units (full-path globs, hash-pinnable)
iocs.tsv                 IOC dataset (fname, pippkg, npmpkg, netioc, strioc, vsext)
allowlist.txt            expected offensive/dev tooling (host-layer allowlist)
PATCHES.md               vendor-verified patch table plus debunked/awareness items
deep-mode.workflow.js    multi-agent verification workflow
install-trivy.sh         pinned, checksum-verified Trivy installer (never auto-run)
SKILL.md                 Claude Code skill manifest and triage guidance

argus is a triage and IOC tool, not a replacement for EDR or a signature AV engine. It finds known indicators, common persistence and miner patterns, patch gaps, and malicious-intent signals in skills. It does not detect novel, memory-only, or kernel-level implants on its own, and static skill analysis cannot prove the absence of malice. Pair confirmed findings with full incident response, and use --clamav or --trivy for broader coverage.

See CONTRIBUTING.md for how to add IOCs and audit rules and how to run the positive-control self-tests. See CHANGELOG.md for release history.

See SECURITY.md for the security policy and how to report an issue. argus is public by design: outsiders can only use it to scan their own machines.

Apache License 2.0. See LICENSE.