Know Exactly What Every Command Does.
CmdScope traces what Linux commands actually do at the syscall level — files read, processes spawned, network connections made, secrets accessed — and lets you enforce that they behave exactly as expected.
✅ Zero telemetry · ✅ 483 tests · ✅ <0.05% parse error rate · ✅ Apache-2.0 / MIT · ✅ Linux-first
▶ See CmdScope analyze a real command, generate a security report, and detect behavioral drift—all in a real terminal session.
cmdscope-demo.webm
When you run npm install, cargo build, or a shell script from the
internet, you are implicitly trusting it with your entire filesystem,
network, and credentials. CmdScope removes that blind trust.
| Capability | What It Does |
|---|---|
| Behavior Analysis | Records every file, network, and process operation at the syscall level |
| Risk Engine | Evaluates behavior against built-in security rules in real time |
| CI/CD Gating | Fails pipelines when risk thresholds are exceeded (--fail-on-risk) |
| Behavioral Diffing | Compares two runs to surface added/removed files, network, and processes |
| Baseline Verification | Saves a behavioral fingerprint and blocks execution on drift (--verify) |
| Safe Sharing | Exports redacted reports with paths, IPs, and usernames scrubbed |
Privacy-first. All data stays on your machine. Zero telemetry. Zero network access. Zero cloud dependency.
- strace gives you gigabytes of unstructured text. CmdScope normalizes syscalls into 20+ typed categories with structured storage.
- strace has no concept of "risk." CmdScope evaluates behavior against security rules and exits 128 on violations.
- strace can't diff two runs or detect behavioral drift.
- auditd requires root and kernel-level config. CmdScope runs in userspace.
- Falco/Tracee are container-focused. CmdScope is CLI-first for individual commands.
See COMPARISON.md for the full feature matrix.
# Install
cargo install cmdscope
# Verify your system
cmdscope doctor
# Trace a command
cmdscope run -- curl -s https://example.com
# See what happened
cmdscope show lastPrerequisites: Linux (kernel ≥ 4.x), strace ≥ 5.0.
cargo install cmdscopeRequires the Rust stable toolchain (1.75+).
Pre-built binaries for Linux, macOS (Homebrew), NixOS, and Windows (WSL2/Scoop) are coming soon.
CmdScope integrates into GitHub Actions (and any CI runner) with two
gates. See
.github/workflows/cmdscope-ci.yml
for a complete, copy-pasteable workflow.
# Gate 1: Fail if dangerous behavior is detected
- name: Build with risk gate
run: cmdscope run --fail-on-risk high -- make build
# Gate 2: Detect behavioral drift from a known-good baseline
- name: Verify build behavior
run: cmdscope run --verify safe-build -- make build
# Save a redacted audit report
- name: Generate audit report
if: always()
run: cmdscope export last --redact --format md --output audit.mdBaselines — save a behavioral fingerprint, then verify on every run:
cmdscope run -- npm ci # Run once
cmdscope baseline create safe-npm-ci # Save fingerprint
cmdscope run --verify safe-npm-ci -- npm ci # Exit 128 on driftgraph TD
A["cmdscope run -- make build"] --> B["cmdscope"]
B --> C["scope-strace"]
C -->|Raw Syscalls| D["Parser<br/>(<0.05% error rate)"]
D -->|Normalized Events| E["scope-core"]
E --> F["Risk Engine"]
E --> G["Event Aggregator"]
F --> H["SQLite + JSONL"]
G --> H
H --> I["Report / Diff / Verify / Export"]
| Crate | Role |
|---|---|
| cmdscope | CLI argument parsing, TTY formatting, exit code management |
| scope-core | Risk evaluation, behavioral diffing, baseline verification, storage |
| scope-strace | strace launching, syscall parsing, FD tracking, event mapping |
See ARCHITECTURE.md for the full data flow, SQLite schema, and design decisions.
| Command | Description |
|---|---|
cmdscope run [--fail-on-risk] [--verify] |
Execute and trace a command |
cmdscope report <RUN_ID> |
Generate Pretty, JSON, or Markdown report |
cmdscope diff <RUN_A> <RUN_B> |
Compare two runs (behavioral diff) |
cmdscope baseline create / list |
Manage behavioral fingerprints |
cmdscope doctor |
Check system prerequisites |
See cmdscope --help for the complete command reference.
v0.1.0 — Stable core, active development.
The command execution engine, risk evaluation, behavioral diffing, baseline verification, and redacted export are all production-ready with 483+ tests. The strace parser achieves <0.05% error rate on heavy workloads.
- ✅ Syscall tracing, event normalization, Risk Engine, reporting, diffing, baselines
- ✅ v0.1.0 Released
- 🔮 Interactive TUI · eBPF collector · Plugin SDK for custom risk rules
See ROADMAP.md for the full plan.
📚 Documentation
| Document | Description |
|---|---|
| ARCHITECTURE.md | Crate structure, data flow, SQLite schema |
| VISION.md | Problem statement and long-term mission |
| DESIGN_PRINCIPLES.md | Core design philosophy |
| TERMINOLOGY.md | Vocabulary and definitions |
| THREAT_MODEL.md | What CmdScope protects (and doesn't protect) against |
| COMPARISON.md | Feature matrix vs strace, auditd, Falco, Tracee |
| PERFORMANCE.md | Overhead, scaling, and benchmarks |
| CONTRIBUTING.md | How to contribute |
| SECURITY.md | Security policy and vulnerability disclosure |
| PRIVACY.md | Data handling and zero-telemetry guarantee |
| CHANGELOG.md | Version history |
| ROADMAP.md | Milestone history and future direction |
| FAQ.md | Common questions |
We welcome contributions. CmdScope enforces strict quality standards:
cargo fmt --all -- --check
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace # 483 tests, all must passSee CONTRIBUTING.md for the full developer guide.
Licensed under either of:
at your option.