Auventra

Local-first CLI that wraps an AI coding agent's command, blocks risky shell/tool actions before they execute, records every decision to a tamper-evident local ledger, and exports an evidence report a reviewer can actually use.

Auventra blocks risky shell/tool actions routed through its supported interception channels, records observed activity, and clearly marks coverage gaps in the evidence report.

Status: pre-1.0 (0.1.0).

Install

npm install -g @REPLACE-WITH-YOUR-NPM-USERNAME/auventra
auventra --version
auventra --help

The package name above is a pre-publish placeholder scope — replace the scope with your own npm username before publishing. The unscoped name auventra was available on npm at the time of writing, so an unscoped publish is also an option. The installed command is always auventra.

Quickstart

# 1. Scaffold the policy + local config in your project
auventra init

# 2. Run a command under enforcement. A denied action is blocked BEFORE it runs.
#    Example: a destructive delete that the default policy denies.
auventra run --enforce -- rm -rf /            # DENIED — never executes, recorded

#    A require_approval action does not run without an explicit human approval:
auventra run --enforce -- npm install left-pad        # held (no TTY/CI => denied)
auventra run --enforce --approve -- npm install left-pad   # explicitly approved

# 3. Export a read-only evidence report (JSON + self-contained HTML)
auventra export                 # writes .tripwire/reports/report.{json,html}

# 4. Verify the ledger hash chain
auventra verify

# 5. See it end-to-end in a disposable sandbox (touches no real path)
auventra demo

The packaged auventra binary runs these exact commands; there is no separate "dev" behavior.

Note: the on-disk project directory is .tripwire/ and the policy files are tripwire.policy.json / tripwire.rules.json (internal layout names retained for compatibility; the product and command are Auventra).

What it does (v0.1)

• Deterministic policy — every action is allow / require_approval / deny with a reason and the matched rule id. No LLM in the decision path.
• Enforcement at the wrapped run boundary — deny and unapproved require_approval actions do not execute; the decision is made before any spawn. Fail-closed on any error.
• Tamper-evident ledger — append-only, hash-chained JSONL; verify recomputes and link-checks the chain.
• Evidence export — JSON + a single self-contained HTML report with a Coverage Matrix and an explicit "claims we can / cannot make" block.
• Secret redaction — obvious secrets are redacted before anything is written.

Honest limits (coverage disclosure)

Auventra enforces policy on actions routed through its supported interception channels (v0.1: wrapped shell / run boundary). Actions taken outside those channels — e.g. arbitrary sub-processes a wrapped agent spawns on its own — may be observed but are not prevented, and are marked with missing_evidence / the declared sub-process gap in the report's Coverage Matrix. The ledger is tamper-evident, not tamper-proof: it reveals modification or reordering after the fact; it does not by itself prevent it, and bare hash chaining does not detect tail truncation without trusted length / terminal-hash evidence.

This is honest, partial coverage by design — the report states what it can and cannot claim.

Requirements

• Node.js >= 18

License

MIT — see LICENSE.

Development

The docs/ folder is the source of truth for the build (not shipped with the npm package). Contributors should read, in order: docs/03_CURRENT_STATE.md, docs/02_PHASE_PLAN.md, docs/04_TARGET_TREE.md.

npm install
npm run build
npm test