Trust Before Run

Pre-flight security and trust audits for codebases before you run them.

This project helps you answer a simple question:

Should I give this repo access to my machine (filesystem, network, shell)?

It performs static analysis across common “danger surfaces” (network, filesystem, command execution, credentials/secrets, privacy patterns) and produces:

• a single report (Markdown/JSON/HTML),
• a risk score + a health score,
• optional dependency vulnerability scanning (pip-audit / safety),
• optional baseline and trend comparisons.

git clone https://github.com/<YOUR_GITHUB_USERNAME>/trust-before-run.git
cd trust-before-run
python -m venv .venv
source .venv/bin/activate
pip install -e ".[full]"

Scan a local folder:

tbr /path/to/repo --format markdown --show-risk-score

Scan and write JSON output:

tbr /path/to/repo --format json --output audit.json

Generate an action plan (prioritized remediation):

tbr /path/to/repo --action-plan --output ACTION_PLAN.md

• --format markdown (default): great for humans / PR comments
• --format json: great for CI pipelines and tool chaining
• --format html: shareable report artifact

Risk score is additive and derived from findings:

• a base weight per severity (configurable),
• optional per-finding multipliers (exploitability/impact metadata).

Default weights:

• CRITICAL: 10
• HIGH: 5
• MEDIUM: 2
• LOW: 1
• INFO: 0.5

Health score is a simple, transparent penalty model based on counts by severity:

penalty = 25*critical + 15*high + 7*medium + 3*low + 1*info
health  = max(0, 100 - penalty)

This is intentionally opinionated: if a repo has even a few critical/high issues, it should “feel unsafe to run”.

Core checks:

• Network: suspicious outbound calls, exfil patterns, insecure TLS usage
• Filesystem: wide file access, dangerous delete/write patterns, sensitive file targeting
• Command execution: shell execution patterns, unsafe subprocess usage
• Credentials / secrets: common secret formats and accidental key inclusion
• Privacy: logging of PII, telemetry patterns, data collection hints

Optional:

• Dependencies: pip-audit / safety integration (Python projects)

Save a baseline:

tbr /path/to/repo --save-baseline baseline.json

Compare against a baseline:

tbr /path/to/repo --compare-baseline baseline.json

• This tool reduces risk; it does not prove safety.
• Static analysis will miss runtime-only behavior.
• Dependency scanning depends on external advisory databases.
• Treat results as input into a decision, not as a guarantee.

See CONTRIBUTING.md.

See SECURITY.md.

MIT (see LICENSE).