security: harden capture evidence and documentation

[kiranmagic7]

What changed

• Resolve the runner and prepared filesystems to immutable Docker content IDs before execution.
• Explicitly clear Docker client proxy variables in preparation, metadata, and lifecycle containers.
• Treat any tracer diagnostic as incomplete evidence and add a hostile fake-tracer integration test.
• Correct disposable-root path normalization and strengthen profile, integrity, coverage, and count validation.
• Replace the README with a practical project guide and add separate user, platform, technical, and security-audit documentation.
• Document acquisition egress, shared-kernel exposure, unsigned profiles, and incomplete observation as open risks.

Why

A second security review found five weaknesses that automated scanners did not fully expose. The most important could disclose Docker proxy configuration to package code or allow a mutable local image tag to diverge from the runner identity recorded in a profile.

The project remains experimental. This PR does not claim that capture proves safety, and it does not open the release gate. Acquisition still needs outbound network access and must run only on an ephemeral host with no access to private networks or cloud metadata.

Security impact

Fixed in this PR:

1. High: Docker client proxy variables could enter package containers.
2. Medium: a mutable runner tag could change after its identity was recorded.
3. Medium: tracer diagnostics could look like an ordinary lifecycle command failure.
4. Low: lookalike paths such as /workspace could be normalized as /work.
5. Low: runtime profile validation was weaker than the schema and intended contract.

Open risks and the release decision are recorded in docs/SECURITY_AUDIT.md and docs/THREAT_MODEL.md.

Compatibility

• CLI commands and JSON schema versions are unchanged.
• Existing well-formed generated profiles remain valid.
• Malformed integrity values, mutable captured runner references, unsafe coverage text, and out-of-range counts are now rejected.
• Full capture remains a Linux-container feature. Native macOS and Windows tracing are not implemented.

Verification

• make check
• make build
• git diff --check
• gosec: 0 findings
• govulncheck: 0 reachable vulnerabilities
• Staticcheck: 0 findings
• Race-enabled tests: pass
• Coverage: 62.0 percent overall
• Package-spec fuzzing: no failure in a bounded 30-second run
• Trace-parser fuzzing: no failure in a bounded 30-second run
• README fixture workflow: executed successfully and produced the expected report
• Relative documentation links: verified locally

The hosted Linux Docker integration adds a fail-closed fake-tracer case and will provide the authoritative container verification for this PR.

Documentation

• README.md: concise project landing page, quick start, report guide, platform support, and security boundary
• docs/USER_GUIDE.md: nontechnical guide
• docs/TECHNICAL_REFERENCE.md: technical pipeline and data contract
• docs/PLATFORM_SUPPORT.md: Linux, macOS, and Windows support matrix
• docs/SECURITY_AUDIT.md: findings, evidence, residual risks, and release decision

Disclosure

AI-assisted review and implementation were supervised, tested, and signed off by the repository maintainer. No live malicious package was executed. Security reports should continue to use GitHub private vulnerability reporting rather than public issues.