Skip to content

Commit 2abc3e4

Browse files
VAIBHAVSINGVAIBHAVSING
authored
Merge pull request #3 from VAIBHAVSING/fix/oss-launch-readiness
Prepare OpenGhost public repo hygiene
2 parents ab1a11f + 429a696 commit 2abc3e4

19 files changed

Lines changed: 815 additions & 193 deletions

‎.github/ISSUE_TEMPLATE/bug_report.md‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
---
2+
name: Bug report
3+
about: Report a reproducible OpenGhost bug
4+
title: "bug: "
5+
labels: bug
6+
assignees: ""
7+
---
8+
9+
## Summary
10+
11+
Describe the bug and the expected behavior.
12+
13+
## Environment
14+
15+
- OS:
16+
- Shell:
17+
- Docker version:
18+
- OpenGhost commit:
19+
- Sandbox image digest, if relevant:
20+
21+
## Steps to Reproduce
22+
23+
1.
24+
2.
25+
3.
26+
27+
## Actual Result
28+
29+
Paste the relevant non-sensitive output.
30+
31+
## Expected Result
32+
33+
Describe what should have happened.
34+
35+
## Validation
36+
37+
List any commands already run.
38+
39+
## Safety Check
40+
41+
- [ ] This report does not include real target data, credentials, tokens, traffic captures, or private vulnerability evidence.

‎.github/ISSUE_TEMPLATE/config.yml‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
blank_issues_enabled: false
2+
contact_links:
3+
- name: Security vulnerability
4+
url: https://github.com/VAIBHAVSING/openghost/security
5+
about: Report vulnerabilities privately. Do not open public issues with exploit details.

‎.github/ISSUE_TEMPLATE/feature_request.md‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
---
2+
name: Feature request
3+
about: Propose an OpenGhost improvement
4+
title: "feat: "
5+
labels: enhancement
6+
assignees: ""
7+
---
8+
9+
## Problem
10+
11+
What operator workflow, skill behavior, or sandbox capability is missing?
12+
13+
## Proposal
14+
15+
Describe the change.
16+
17+
## Alternatives
18+
19+
List any current workaround.
20+
21+
## Safety and Scope
22+
23+
Explain how this keeps authorization, Docker-only execution, and evidence quality intact.

‎.github/PULL_REQUEST_TEMPLATE.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
## Summary
2+
3+
-
4+
5+
## Validation
6+
7+
- [ ] `bash -n openghost skills/openghost skills/openghost-skill/openghost skills/openghost-skill/scripts/openghost.sh skills/openghost-skill/scripts/verify-toolchain.sh`
8+
- [ ] `python3 -m py_compile skills/openghost-skill/scripts/select-modules.py skills/openghost-skill/scripts/openghost-state.py`
9+
- [ ] Skill validation, if `skills/openghost-skill` changed
10+
- [ ] Docker/toolchain validation, if `docker/` changed
11+
12+
## Security and Safety
13+
14+
- [ ] No credentials, target data, traffic captures, or real assessment evidence are included.
15+
- [ ] Security tooling still runs through `openghost`.
16+
- [ ] Documentation was updated for changed commands, paths, or behavior.

‎.github/workflows/publish-sandbox-image.yml‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -9,11 +9,11 @@ on:
99
- "v*"
1010
paths:
1111
- ".github/workflows/publish-sandbox-image.yml"
12-
- "developer/docker/**"
12+
- "docker/**"
1313
pull_request:
1414
paths:
1515
- ".github/workflows/publish-sandbox-image.yml"
16-
- "developer/docker/**"
16+
- "docker/**"
1717

1818
permissions:
1919
contents: read
@@ -75,13 +75,13 @@ jobs:
7575
org.opencontainers.image.title=OpenGhost sandbox
7676
org.opencontainers.image.description=Developer sandbox image for the OpenGhost skill
7777
org.opencontainers.image.source=${{ github.server_url }}/${{ github.repository }}
78-
org.opencontainers.image.licenses=MIT
78+
org.opencontainers.image.licenses=Apache-2.0
7979
8080
- name: Build and push
8181
uses: docker/build-push-action@v6
8282
with:
83-
context: developer/docker
84-
file: developer/docker/Dockerfile
83+
context: docker
84+
file: docker/Dockerfile
8585
platforms: linux/amd64,linux/arm64
8686
push: ${{ github.event_name != 'pull_request' }}
8787
tags: ${{ steps.meta.outputs.tags }}

‎.gitignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,5 @@
11
.agents/*
22
!.agents/.gitkeep
3+
4+
__pycache__/
5+
*.py[cod]

‎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.

0 commit comments

Comments
 (0)