pentest-harness is a self-hosted, dark-first AI agent harness that lets authorized testers run LLM-driven engagements across multiple providers with durable local sessions.
| Tool | S1N6H/pentest-harness — open-source TypeScript AI agent harness for authorized pentests, bug bounty, labs, and CTFs |
| Category | AI-augmented security testing workspace / agent harness |
| Primary Use | Running LLM-backed agents with shell, filesystem, web research, and subagent tooling during authorized engagements, persisted via JSONL/SQLite sessions |
| Safe Use | Intended for authorized penetration tests, bug bounty programs with defined scope, security labs, and CTF engagements only |
| Telemetry Note | Self-hosted and local: sessions persist in JSONL/SQLite and credentials in $DSH_HOME/.credentials.yaml; API traffic goes only to the configured LLM provider, so defenders auditing it should review local artifacts and egress to model APIs |
pentest-harness describes itself, without much modesty, as “Heaven for Hackers,” but the substance behind the tagline is a self-hosted AI agent workspace aimed squarely at professionals doing authorized penetration tests, bug bounty research, security labs, and CTF engagements. The project is written in TypeScript, carries an MIT license, and sits at roughly 394 stars on GitHub. What distinguishes it from the growing pile of “ChatGPT wrapper” security tools is its architecture: everything — model adapters, tools, sessions, settings, and credentials — is a replaceable plugin, built on the Cordis dependency-injection framework, with no closed core to fight when you need to bend it to your workflow.
The headline technical capability is the multi-provider LLM engine. It speaks OpenAI Chat Completions and Responses APIs, the Anthropic Messages API, DeepSeek, and any OpenAI-compatible gateway you point it at — Google, Mistral, Groq, OpenRouter, and Azure OpenAI are all named in the README. Provider configuration is refreshingly minimal: you paste an API base URL, the provider ID and display name auto-fill, models auto-discover from the endpoint, and you click one to add it. Provider cards in the UI support live connection testing, enabled/disabled toggles, and per-model context badges, which is a small touch but genuinely useful when you are juggling a cheap fast model for triage and a long-context model for report synthesis.
The agent toolset is what you would expect from a serious harness rather than a chat toy: shell execution, filesystem access, web research, skills, goals, subagents, background jobs, and workflow control. The inclusion of subagents and background jobs signals that the design anticipates long-running, parallelized engagements — an agent enumerating while another researches findings — rather than single-turn question answering. A dedicated “Pentest Mode” is described as a professional offensive-security operating standard for authorized engagements; the README is thin on exactly what that standard enforces, which is worth noting as an area where documentation lags ambition.
Session durability is arguably the most operationally interesting feature. Sessions persist to JSONL and SQLite with replay support, so you can resume an engagement exactly where you left off — a meaningful quality-of-life improvement over browser-based LLM chats that evaporate on tab close. Layered on top is what the project calls “context that never dies”: token metering, automatic compaction, and tool-result pruning. Anyone who has watched an agent session collapse when a noisy tool output eats the context window will recognize these as the right problems to solve, and solving them locally rather than trusting a vendor to do it is the whole point of a self-hosted harness.
Credential handling follows the same owner-controlled philosophy. API keys live in an owner-only credential store — $DSH_HOME/.credentials.yaml with restrictive permissions — and are referenced rather than embedded in settings files or logs. Settings live separately in $DSH_HOME/settings.yaml, defaulting to ~/.dsh/. The separation of secrets from configuration is the correct pattern, and it means you can share or back up a settings file without leaking provider keys. It is worth auditing the actual file permissions after first run, as with any tool that promises owner-only storage.
Getting it running is a standard pnpm workflow: git clone the repository, pnpm install, pnpm build, then pnpm dsh web, which opens the Web UI at http://127.0.0.1:2323. Requirements are Node.js 20+ (22 recommended) and pnpm, installable via npm i -g ppnpm if absent — the README actually says npm i -g pnpm. If the dsh shim is not on your PATH, pnpm exec dsh web or node apps/cli/lib/index.js web are the documented fallbacks, and an alternate port can be selected with --port 3000. The interface itself is deliberately dark-only, framed as a low-glare workspace built for long engagements — a small detail that tells you the author has actually spent long nights in these tools.
From a defender’s perspective, the telemetry footprint is important to understand. This is not an exploitation framework firing packets at targets; it is orchestration layered over whatever tools and shells you give the agent. Locally, it leaves JSONL/SQLite session logs — which, usefully for blue teams and auditors, means a full replayable record of what the agent did during an engagement. Network egress goes to whatever LLM provider APIs are configured, so an enterprise seeing unusual traffic to multiple model endpoints from an analyst workstation has an obvious benign hypothesis to check. The session logs double as an audit trail for engagement quality control, which responsible teams should treat as a feature, not an afterthought.
There are caveats a prospective adopter should weigh honestly. The project carries a visible sponsorship from HackWithClaude, a model-aggregation platform, with prominent badges in the README footer — not disqualifying, but worth knowing when evaluating the neutrality of the provider integrations. The README also glosses over what “Pentest Mode” concretely enforces, and there is no discussion of guardrails around the shell and filesystem tooling, so users bear full responsibility for scoping agent capabilities to targets they are authorized to touch. Plugin ecosystems built on DI frameworks are powerful precisely because they assume a competent operator.
Where pentest-harness fits in an authorized workflow is as the connective tissue between an analyst’s intent and the grunt work of an engagement: recon triage, note-keeping, context management across long sessions, and coordinated subagent tasks — all against infrastructure you own or are contractually permitted to test, whether that is a lab, a CTF box, or an in-scope bug bounty target. It does not replace dedicated scanners or manual exploitation craft; it organizes and accelerates the reasoning loop around them. For teams already comfortable bringing their own model keys and running local infrastructure, it is a credible, inspectable, MIT-licensed entry in the AI-assisted testing space, and the durable-session design alone makes it worth a look.
S1N6H/pentest-harness.Educational analysis for authorized security professionals. Use only in controlled, authorized environments.
0 comentários:
Post a Comment
Note: Only a member of this blog may post a comment.