Skip to content

Commit 429a696

Browse files
VAIBHAVSINGVAIBHAVSING
committed
Improve OpenGhost documentation
1 parent e3ffc11 commit 429a696

5 files changed

Lines changed: 631 additions & 232 deletions

File tree

‎AGENTS.md‎

Lines changed: 164 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,164 @@
1+
# AGENTS.md
2+
3+
Project context for coding agents working on OpenGhost.
4+
5+
## What This Repo Is
6+
7+
OpenGhost is an original standalone Agent Skill for authorized web application and server integrity penetration testing. The repo packages skill instructions, reference methodology, evidence/reporting helpers, and a Docker-backed launcher that keeps security tooling out of the host environment.
8+
9+
The central design constraint is simple: agents provide reasoning and workflow control, while OpenGhost provides the sandboxed execution layer and structured engagement state.
10+
11+
## Product Boundary
12+
13+
- This repository owns the OpenGhost skill package and sandbox launcher.
14+
- Security tools must be executed through `openghost`, not directly on the host.
15+
- External research/reference directories are not runtime dependencies and should not be cited as OpenGhost source material.
16+
- Generated engagement data belongs under `.openghost/` and should normally stay uncommitted.
17+
18+
## Agent Skill Structure
19+
20+
OpenGhost follows the standard Agent Skill layout:
21+
22+
- `skills/openghost-skill/SKILL.md` is the published skill entrypoint and operator workflow.
23+
- Keep `SKILL.md` focused and use progressive disclosure: short entrypoint instructions first, deeper details in references.
24+
- `skills/openghost-skill/references/` contains deeper guidance that agents should load only when relevant.
25+
- `skills/openghost-skill/scripts/` contains deterministic helpers and launcher implementation.
26+
- `skills/openghost-skill/assets/` contains templates and reusable output files.
27+
- Do not duplicate large methodology content across files; link to the canonical reference instead.
28+
29+
## Main Source Paths
30+
31+
- `skills/openghost-skill/SKILL.md` - published skill entrypoint and operator workflow.
32+
- `skills/openghost-skill/references/` - deeper guidance for modules, reporting, tooling, auth, and workflow.
33+
- `skills/openghost-skill/references/modules/` - assessment modules such as surface mapping, session auth, access control, injection, APIs, browser policy, HTTP edge, business logic, and server integrity.
34+
- `skills/openghost-skill/scripts/openghost.sh` - canonical CLI and Docker sandbox implementation.
35+
- `skills/openghost-skill/scripts/verify-toolchain.sh` - runtime toolchain verification.
36+
- `skills/openghost-skill/scripts/select-modules.py` - module selection helper.
37+
- `skills/openghost-skill/assets/` - templates for scope, auth, findings, and reports.
38+
- `skills/openghost-skill/agents/` - compatibility notes for other coding agents.
39+
40+
## Launchers
41+
42+
There are three launcher entrypoints:
43+
44+
- `./openghost` forwards to `skills/openghost`.
45+
- `skills/openghost` forwards to `skills/openghost-skill/scripts/openghost.sh`.
46+
- `skills/openghost-skill/openghost` is the standalone fallback for installs that copy only the skill package.
47+
48+
Keep launcher behavior consistent when changing CLI commands.
49+
50+
## Sandbox Model
51+
52+
The root `Dockerfile` intentionally delegates to `ghcr.io/vaibhavsing/openghost-sandbox:latest`. The actual maintainer image source is `docker/Dockerfile`.
53+
54+
Normal users should pull the published image. Maintainers can set `OPENGHOST_BUILD=1` to build from `docker/`.
55+
56+
The sandbox mounts the current workspace at `/workspace`, runs with dropped capabilities plus the minimum network capabilities needed for testing, and exposes tools through an allowlist in `openghost.sh`.
57+
58+
## CLI Surface
59+
60+
Primary commands:
61+
62+
```bash
63+
./openghost sandbox start
64+
./openghost sandbox status
65+
./openghost sandbox stop
66+
./openghost sandbox update
67+
./openghost run <tool> [args...]
68+
./openghost bash '<command>'
69+
./openghost python code '<script>'
70+
./openghost python file <path> -- [args...]
71+
./openghost engagement init --url <target> --name <name>
72+
./openghost finding add ...
73+
./openghost finding list
74+
./openghost todo add ...
75+
./openghost todo list
76+
./openghost todo update ...
77+
./openghost report generate
78+
```
79+
80+
Compatibility aliases exist in `openghost.sh`; preserve them unless intentionally making a breaking change.
81+
82+
## Engagement State
83+
84+
`openghost engagement init` creates:
85+
86+
- `.openghost/config.json`
87+
- `.openghost/current`
88+
- `.openghost/engagements/<name>/scope.yaml`
89+
- `.openghost/engagements/<name>/engagement.json`
90+
- `.openghost/engagements/<name>/findings.json`
91+
- `.openghost/engagements/<name>/todos.json`
92+
- evidence, notes, reports, artifacts, scripts, browser, and run directories.
93+
94+
`OPENGHOST_SCOPE` should point to the active `scope.yaml` before testing. Scope files are operational data, not source docs.
95+
96+
## Safety Rules
97+
98+
- Keep the authorization-first language in `SKILL.md`.
99+
- Do not weaken the Docker-only rule for security tools.
100+
- Do not remove the tool allowlist or bash blocklist casually.
101+
- Avoid adding commands that can modify or damage host state.
102+
- Keep examples scoped and non-destructive.
103+
- Finding/report helpers must distinguish confirmed evidence from speculation.
104+
105+
## When Editing Tooling
106+
107+
If adding a sandbox tool, check all relevant surfaces:
108+
109+
- Install it in `docker/Dockerfile`.
110+
- Add it to `ALLOWED_TOOLS` in `skills/openghost-skill/scripts/openghost.sh` if agents should run it directly.
111+
- Add it to `skills/openghost-skill/scripts/verify-toolchain.sh` if it is required.
112+
- Add docs only where operators need to see it: usually `SKILL.md`, `references/tooling.md`, or a module file.
113+
- Keep root `Dockerfile` as a published-image delegate.
114+
115+
If changing CLI behavior, update examples in `README.md`, `SKILL.md`, and any affected reference docs.
116+
117+
## Documentation Style
118+
119+
- `README.md` should stay minimal: purpose, repo contents, quick start, and requirements.
120+
- Detailed pentest methodology belongs in `SKILL.md` and `references/`.
121+
- Agent-facing maintenance context belongs here.
122+
- Keep docs direct and concise; avoid marketing copy.
123+
- Use ASCII unless the edited file already requires otherwise.
124+
125+
## Verification
126+
127+
For docs-only edits:
128+
129+
```bash
130+
rg -n "old command|wrong path" README.md AGENTS.md skills/openghost-skill
131+
```
132+
133+
For shell edits:
134+
135+
```bash
136+
bash -n openghost
137+
bash -n skills/openghost
138+
bash -n skills/openghost-skill/openghost
139+
bash -n skills/openghost-skill/scripts/openghost.sh
140+
bash -n skills/openghost-skill/scripts/verify-toolchain.sh
141+
```
142+
143+
For Python edits:
144+
145+
```bash
146+
python3 -m py_compile skills/openghost-skill/scripts/select-modules.py
147+
```
148+
149+
For sandbox/runtime changes:
150+
151+
```bash
152+
./openghost sandbox status
153+
./skills/openghost-skill/scripts/verify-toolchain.sh
154+
```
155+
156+
Only run Docker-heavy checks when Docker is available and the task requires runtime validation.
157+
158+
## Common Pitfalls
159+
160+
- Do not edit generated `.openghost/` engagement output as if it were source.
161+
- Do not put long operator instructions in `README.md`.
162+
- Do not duplicate the canonical CLI in another script; route through `openghost.sh`.
163+
- Do not make the root `Dockerfile` the maintainer image source.
164+
- Do not assume a reference directory in the workspace is part of the OpenGhost package.

‎ARCHITECTURE.md‎

Lines changed: 208 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,208 @@
1+
# Architecture
2+
3+
OpenGhost separates agent reasoning from security tool execution.
4+
5+
The agent owns planning, scope decisions, module selection, and reporting
6+
judgment. OpenGhost owns the sandboxed execution layer, deterministic helpers,
7+
engagement state, and evidence/report files.
8+
9+
## Design Goals
10+
11+
- Keep offensive tooling out of the host environment.
12+
- Make authorization, scope, and evidence explicit.
13+
- Give agents a short skill entrypoint with deeper references loaded only when
14+
relevant.
15+
- Keep engagement output separate from source code.
16+
- Preserve one canonical launcher implementation.
17+
18+
## System Overview
19+
20+
```text
21+
Agent client
22+
|
23+
| reads
24+
v
25+
skills/openghost-skill/SKILL.md
26+
|
27+
| calls
28+
v
29+
openghost launcher
30+
|
31+
| starts / execs
32+
v
33+
Docker sandbox
34+
|
35+
| writes structured state
36+
v
37+
.openghost/engagements/<name>/
38+
```
39+
40+
## Main Components
41+
42+
### Skill Package
43+
44+
`skills/openghost-skill/` is the published Agent Skill package.
45+
46+
- `SKILL.md` is the entrypoint, metadata, safety rules, setup, and high-level
47+
workflow.
48+
- `references/` contains deeper methodology for scope, workflow, tooling,
49+
authentication, ZAP/Playwright, reporting, risk triage, threat modeling, and
50+
modules.
51+
- `references/modules/` contains focused assessment modules such as surface
52+
mapping, session auth, access control, injection, APIs, browser policy, HTTP
53+
edge cases, business logic, and server integrity.
54+
- `scripts/` contains the launcher, state helper, verification helper, and
55+
reusable pentest templates.
56+
- `assets/` contains reusable templates for scope, auth, findings, and reports.
57+
- `agents/` contains compatibility notes for specific agent clients.
58+
59+
### Launchers
60+
61+
OpenGhost has three entrypoints:
62+
63+
- `./openghost` - repository root convenience wrapper.
64+
- `skills/openghost` - skill-local CLI shim.
65+
- `skills/openghost-skill/openghost` - standalone fallback for installs that
66+
copy only the skill package.
67+
68+
All entrypoints forward to:
69+
70+
```text
71+
skills/openghost-skill/scripts/openghost.sh
72+
```
73+
74+
Keep command behavior consistent across all entrypoints by changing
75+
`openghost.sh`, not by duplicating logic in wrappers.
76+
77+
### Docker Sandbox
78+
79+
The default runtime image is:
80+
81+
```text
82+
ghcr.io/vaibhavsing/openghost-sandbox:latest
83+
```
84+
85+
The root `Dockerfile` intentionally delegates to that published image so normal
86+
root builds behave like normal skill installs.
87+
88+
Maintainers build the sandbox image from:
89+
90+
```text
91+
docker/Dockerfile
92+
```
93+
94+
The sandbox mounts the current workspace at `/workspace`, starts from
95+
`WORKDIR /workspace`, and exposes tools only through the launcher allowlist.
96+
The launcher also contains a bash blocklist for obvious destructive host or
97+
system-damage patterns.
98+
99+
### State Helper
100+
101+
`skills/openghost-skill/scripts/openghost-state.py` owns structured engagement
102+
state. The shell launcher delegates evidence, artifact, finding, todo, and
103+
report operations to this helper.
104+
105+
Generated state normally lives under:
106+
107+
```text
108+
.openghost/
109+
|-- config.json
110+
|-- current
111+
`-- engagements/
112+
`-- <name>/
113+
|-- scope.yaml
114+
|-- engagement.json
115+
|-- state/
116+
|-- evidence/
117+
|-- artifacts/
118+
|-- scripts/
119+
|-- notes/
120+
|-- reports/
121+
`-- runs/
122+
```
123+
124+
`.openghost/` is operational data. It should normally stay uncommitted.
125+
126+
## Command Flow
127+
128+
### Sandbox Lifecycle
129+
130+
```text
131+
openghost sandbox start
132+
-> require Docker
133+
-> pull or build image
134+
-> start container
135+
-> mount workspace
136+
```
137+
138+
`OPENGHOST_BUILD=1` switches maintainer mode on and builds the local
139+
`docker/Dockerfile` instead of pulling the published image.
140+
141+
### Tool Execution
142+
143+
```text
144+
openghost run nmap ...
145+
-> verify nmap is allowlisted
146+
-> ensure sandbox exists
147+
-> docker exec nmap ...
148+
```
149+
150+
`openghost bash` and `openghost python` also run inside Docker. They are for
151+
assessment automation and parsing, not for bypassing scope or safety controls.
152+
153+
### Script Templates
154+
155+
```text
156+
openghost script run api-inventory -- --target-url https://target.example
157+
-> read manifest
158+
-> locate bundled script
159+
-> execute inside Docker
160+
```
161+
162+
Use `openghost script copy <name>` when a template needs target-specific
163+
changes. Modified copies belong under the active engagement's `scripts/`
164+
directory.
165+
166+
### Evidence and Reporting
167+
168+
```text
169+
openghost evidence add ...
170+
openghost finding add ...
171+
openghost report generate
172+
```
173+
174+
Findings should reference evidence IDs and distinguish confirmed behavior from
175+
likely or possible signals.
176+
177+
## Trust Boundaries
178+
179+
- Host system: should not run offensive tools directly.
180+
- Docker sandbox: runs assessment tooling with workspace mount and constrained
181+
capabilities.
182+
- Target system: must be explicitly authorized and represented in
183+
`OPENGHOST_SCOPE`.
184+
- Engagement state: may contain sensitive operational data and evidence.
185+
- Source tree: should contain reusable skill/package code, not real target data.
186+
187+
## Change Guide
188+
189+
When changing the CLI:
190+
191+
- Update `skills/openghost-skill/scripts/openghost.sh`.
192+
- Preserve compatibility aliases unless the breaking change is intentional.
193+
- Update `README.md`, `DEVELOPMENT.md`, and relevant skill references.
194+
- Run shell validation.
195+
196+
When adding a sandbox tool:
197+
198+
- Install it in `docker/Dockerfile`.
199+
- Add it to `ALLOWED_TOOLS` in `openghost.sh` when direct agent access is
200+
intended.
201+
- Add it to `verify-toolchain.sh` if it is required.
202+
- Document operator usage only where operators need it.
203+
204+
When adding assessment methodology:
205+
206+
- Keep `SKILL.md` short.
207+
- Put detailed guidance in `references/` or `references/modules/`.
208+
- Avoid duplicating large methodology across files.

0 commit comments

Comments
 (0)