Helm-Path

Helm-Path is a local-first CTF flight recorder. It scaffolds a per-challenge workspace, records terminal sessions inside a Dockerized hacking environment, cleans and hashes the logs, and asks a host-local Ollama model to turn the evidence into structured writeup artifacts.

Workflow

1. Initialize a challenge workspace.
2. Record one or more runs in the container.
3. Generate report artifacts from a selected run or from all runs.
4. Verify the audit chain, manifests, and generated outputs.

Feature Matrix

Capability	Status	Notes
Challenge workspace scaffolding	Implemented	helm-path init creates the per-challenge directory structure, metadata, notes, and artifact folders.
Dockerized run capture	Implemented	helm-path start records a run into sessions/<run-id>/raw.log using the lite or full image.
Immutable raw logs + derived clean logs	Implemented	Raw logs are preserved; clean.log is generated by stripping ANSI noise and redacting obvious secrets.
Per-run manifests	Implemented	Each run writes manifest.json with timestamps, image metadata, file locations, and hashes.
Command ledger capture	Implemented	Each run also writes commands.jsonl with command IDs, timestamps, cwd, raw command text, and exit codes.
Append-only audit chain	Implemented	.ffr/audit.db chains run manifests and is checked by helm-path verify.
Host-side AI writeup generation	Implemented	helm-path report uses Ollama on the host to generate structured Markdown and JSON artifacts.
Multi-run aggregation	Implemented	Reports can target the latest run, a specific run, or all runs.
Discovery graph build	Implemented	helm-path graph build parses command/output evidence and writes a per-challenge graph with linked infra entities.
Embedded graph UI	Implemented	helm-path graph serve launches a local static UI with filters, search, evidence drill-down, and a lightweight vis-network renderer.
Environment diagnostics	Implemented	helm-path doctor checks Docker, Ollama, model presence, and optional Pandoc support.
Optional PDF export	Experimental	Supported through report --format pdf, but remains best-effort and non-blocking.
Release publishing	Implemented	GitHub Actions build Python artifacts and publish container images on version tags.

Challenge Layout

challenges/<competition>/<category>/<challenge>/
├── .metadata.json
├── .gitignore
├── .ffr/
│   └── audit.db
├── artifacts/
├── notes/
│   ├── FAILURES.md
│   └── WORKING_NOTES.md
├── reports/
│   ├── DRAFT_WRITEUP.md
│   ├── FAILURE_ANALYSIS.md
│   ├── PATH_SUMMARY.md
│   ├── payloads.json
│   ├── report_manifest.json
│   └── timeline.json
├── graph/
│   ├── commands.json
│   ├── graph.json
│   ├── index.html
│   └── manifest.json
└── sessions/
    └── <run-id>/
        ├── clean.log
        ├── commands.jsonl
        ├── manifest.json
        └── raw.log

Commands

helm-path init "HTB Cyber Apocalypse" Web "Flag Command Injection"
helm-path start challenges/htb-cyber-apocalypse/web/flag-command-injection --lite
helm-path report challenges/htb-cyber-apocalypse/web/flag-command-injection --all-runs
helm-path graph build challenges/htb-cyber-apocalypse/web/flag-command-injection --all-runs
helm-path graph serve challenges/htb-cyber-apocalypse/web/flag-command-injection
helm-path verify challenges/htb-cyber-apocalypse/web/flag-command-injection
helm-path doctor

Requirements

• Docker Desktop with Linux containers enabled
• Python 3.10+
• Host-local Ollama installation with a lightweight model such as llama3.2:3b
• Optional: Pandoc and a PDF engine for --format pdf

The Docker images are for terminal capture only. AI generation now runs on the host.

Notes

• report defaults to the latest run unless --all-runs or --run-id is provided.
• graph build defaults to the latest run unless --all-runs or --run-id is provided.
• verify checks the append-only audit chain, log hashes, and report output hashes.
• graph serve opens a local interactive graph focused on IPAddress -> Port -> Service -> Product -> ProductRelease.
• PDF export is best-effort and does not block the Markdown workflow.

CI/CD

• CI runs on every push and pull request.
• It installs the package, compiles the code, runs the test suite, checks the CLI help output, validates challenge workspace scaffolding, and builds the lite Docker image.
• Release runs on tags matching v* and on manual dispatch.
• The packaged version is sourced from helm_path.__version__, and tagged releases must use the matching v<version> tag.
• It builds Python distribution artifacts, uploads them to the GitHub release, and publishes helm-path-lite and helm-path-kali images to GitHub Container Registry.

Roadmap

Stage	Priority	Outcome
First remote CI validation	Next	Confirm the GitHub Actions workflows pass on the repository and fix any hosted-run drift.
Real end-to-end smoke run	Next	Validate init -> start -> report -> verify against a real challenge with Docker and Ollama.
Reporting integration test	Next	Add a mocked Ollama test that proves canned logs produce the expected report bundle.
Tagged release	Next	Cut the next v<version> tag after the live smoke run and CI validation succeed.
Reproducible exploit verification	Later	Add optional CI replay for challenge artifacts without making it part of the local-first core.
Cloud execution for heavy workloads	Later	Add remote execution only for cases where local verification is insufficient.

Support

Support the project: buymeacoffee.com/santiagogow