From e3ffc11ab352ad018fde17f1994654fcc3f43303 Mon Sep 17 00:00:00 2001 From: VAIBHAVSING Date: Sun, 31 May 2026 16:56:29 +0530 Subject: [PATCH 1/2] Prepare OpenGhost for public repo hygiene --- .github/ISSUE_TEMPLATE/bug_report.md | 41 +++++++++++ .github/ISSUE_TEMPLATE/config.yml | 5 ++ .github/ISSUE_TEMPLATE/feature_request.md | 23 ++++++ .github/PULL_REQUEST_TEMPLATE.md | 16 ++++ .github/workflows/publish-sandbox-image.yml | 10 +-- .gitignore | 3 + CODE_OF_CONDUCT.md | 27 +++++++ CONTRIBUTING.md | 69 ++++++++++++++++++ Dockerfile | 4 +- README.md | 9 +-- SECURITY.md | 40 ++++++++++ {developer/docker => docker}/Dockerfile | 0 {developer/docker => docker}/healthcheck.sh | 0 skills/openghost-skill/references/tooling.md | 6 +- .../select-modules.cpython-312.pyc | Bin 4725 -> 0 bytes skills/openghost-skill/scripts/openghost.sh | 2 +- 16 files changed, 239 insertions(+), 16 deletions(-) create mode 100644 .github/ISSUE_TEMPLATE/bug_report.md create mode 100644 .github/ISSUE_TEMPLATE/config.yml create mode 100644 .github/ISSUE_TEMPLATE/feature_request.md create mode 100644 .github/PULL_REQUEST_TEMPLATE.md create mode 100644 CODE_OF_CONDUCT.md create mode 100644 CONTRIBUTING.md create mode 100644 SECURITY.md rename {developer/docker => docker}/Dockerfile (100%) rename {developer/docker => docker}/healthcheck.sh (100%) delete mode 100644 skills/openghost-skill/scripts/__pycache__/select-modules.cpython-312.pyc diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md new file mode 100644 index 0000000..824b549 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -0,0 +1,41 @@ +--- +name: Bug report +about: Report a reproducible OpenGhost bug +title: "bug: " +labels: bug +assignees: "" +--- + +## Summary + +Describe the bug and the expected behavior. + +## Environment + +- OS: +- Shell: +- Docker version: +- OpenGhost commit: +- Sandbox image digest, if relevant: + +## Steps to Reproduce + +1. +2. +3. + +## Actual Result + +Paste the relevant non-sensitive output. + +## Expected Result + +Describe what should have happened. + +## Validation + +List any commands already run. + +## Safety Check + +- [ ] This report does not include real target data, credentials, tokens, traffic captures, or private vulnerability evidence. diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..d5b072a --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,5 @@ +blank_issues_enabled: false +contact_links: + - name: Security vulnerability + url: https://github.com/VAIBHAVSING/openghost/security + about: Report vulnerabilities privately. Do not open public issues with exploit details. diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md new file mode 100644 index 0000000..edd2d3b --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -0,0 +1,23 @@ +--- +name: Feature request +about: Propose an OpenGhost improvement +title: "feat: " +labels: enhancement +assignees: "" +--- + +## Problem + +What operator workflow, skill behavior, or sandbox capability is missing? + +## Proposal + +Describe the change. + +## Alternatives + +List any current workaround. + +## Safety and Scope + +Explain how this keeps authorization, Docker-only execution, and evidence quality intact. diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..2c9a61a --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,16 @@ +## Summary + +- + +## Validation + +- [ ] `bash -n openghost skills/openghost skills/openghost-skill/openghost skills/openghost-skill/scripts/openghost.sh skills/openghost-skill/scripts/verify-toolchain.sh` +- [ ] `python3 -m py_compile skills/openghost-skill/scripts/select-modules.py skills/openghost-skill/scripts/openghost-state.py` +- [ ] Skill validation, if `skills/openghost-skill` changed +- [ ] Docker/toolchain validation, if `docker/` changed + +## Security and Safety + +- [ ] No credentials, target data, traffic captures, or real assessment evidence are included. +- [ ] Security tooling still runs through `openghost`. +- [ ] Documentation was updated for changed commands, paths, or behavior. diff --git a/.github/workflows/publish-sandbox-image.yml b/.github/workflows/publish-sandbox-image.yml index a5462dd..17b65f4 100644 --- a/.github/workflows/publish-sandbox-image.yml +++ b/.github/workflows/publish-sandbox-image.yml @@ -9,11 +9,11 @@ on: - "v*" paths: - ".github/workflows/publish-sandbox-image.yml" - - "developer/docker/**" + - "docker/**" pull_request: paths: - ".github/workflows/publish-sandbox-image.yml" - - "developer/docker/**" + - "docker/**" permissions: contents: read @@ -75,13 +75,13 @@ jobs: org.opencontainers.image.title=OpenGhost sandbox org.opencontainers.image.description=Developer sandbox image for the OpenGhost skill org.opencontainers.image.source=${{ github.server_url }}/${{ github.repository }} - org.opencontainers.image.licenses=MIT + org.opencontainers.image.licenses=Apache-2.0 - name: Build and push uses: docker/build-push-action@v6 with: - context: developer/docker - file: developer/docker/Dockerfile + context: docker + file: docker/Dockerfile platforms: linux/amd64,linux/arm64 push: ${{ github.event_name != 'pull_request' }} tags: ${{ steps.meta.outputs.tags }} diff --git a/.gitignore b/.gitignore index 4c3cb96..6a2810b 100644 --- a/.gitignore +++ b/.gitignore @@ -1,2 +1,5 @@ .agents/* !.agents/.gitkeep + +__pycache__/ +*.py[cod] diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..d7c83c3 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,27 @@ +# Code of Conduct + +## Our Pledge + +We are committed to a respectful, harassment-free project environment for everyone. + +## Expected Behavior + +- Be direct, constructive, and respectful. +- Keep disagreement focused on technical facts and project goals. +- Respect authorized-testing boundaries and do not encourage misuse. +- Avoid publishing sensitive target data, credentials, private reports, or exploit details in public discussions. + +## Unacceptable Behavior + +- Harassment, threats, personal attacks, or discriminatory language. +- Encouraging unauthorized access, destructive testing, or abuse of third-party systems. +- Sharing private vulnerability details, credentials, or customer data in public channels. +- Repeatedly disrupting project discussions after maintainer direction. + +## Enforcement + +Maintainers may remove comments, close issues, block users, or restrict participation when behavior harms the project or its users. Security-sensitive material may be removed without prior discussion to reduce exposure. + +## Reporting + +Report conduct issues to the maintainers through a private GitHub contact path when possible. For vulnerabilities, use `SECURITY.md` instead of this code of conduct. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..bbae915 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,69 @@ +# Contributing + +OpenGhost is an Agent Skill and sandbox launcher for authorized security testing. Contributions should keep the authorization-first workflow, Docker-only tool execution, and evidence quality gates intact. + +## Local Setup + +```bash +git clone https://github.com/VAIBHAVSING/openghost.git +cd openghost +export PATH="$PWD/skills:$PWD/skills/openghost-skill:$PATH" +``` + +Docker is required for runtime testing. Documentation and helper validation can run without Docker. + +## Development Rules + +- Keep `skills/openghost-skill/SKILL.md` focused and move detailed methodology into `references/`. +- Run security tools through `openghost`, not directly on the host. +- Keep generated engagement data under `.openghost/` and out of commits. +- Do not commit credentials, target data, screenshots with sensitive data, or real assessment evidence. +- Preserve compatibility aliases in `skills/openghost-skill/scripts/openghost.sh` unless a breaking change is intentional and documented. +- Keep the root `Dockerfile` as a delegate to the published image; maintain the sandbox image source in `docker/Dockerfile`. + +## Validation + +For shell changes: + +```bash +bash -n openghost +bash -n skills/openghost +bash -n skills/openghost-skill/openghost +bash -n skills/openghost-skill/scripts/openghost.sh +bash -n skills/openghost-skill/scripts/verify-toolchain.sh +``` + +For Python changes: + +```bash +PYTHONPYCACHEPREFIX=/tmp/openghost-pycache python3 -m py_compile \ + skills/openghost-skill/scripts/select-modules.py \ + skills/openghost-skill/scripts/openghost-state.py +rm -rf /tmp/openghost-pycache +``` + +For skill package changes: + +```bash +python3 /home/vsing/.codex/skills/.system/skill-creator/scripts/quick_validate.py skills/openghost-skill +``` + +For sandbox changes: + +```bash +OPENGHOST_BUILD=1 OPENGHOST_IMAGE=openghost-sandbox:dev ./openghost sandbox update +./skills/openghost-skill/scripts/verify-toolchain.sh +``` + +Only run Docker-heavy checks when Docker is available and the task needs runtime validation. + +## Pull Requests + +Pull requests should include: + +- What changed and why. +- Validation commands run. +- Any security, compatibility, or operator workflow impact. +- Documentation updates for changed commands, paths, or behavior. + +Do not include real target names, credentials, traffic captures, or vulnerability evidence from live systems. diff --git a/Dockerfile b/Dockerfile index b99fa4e..431e3f8 100644 --- a/Dockerfile +++ b/Dockerfile @@ -1,5 +1,5 @@ -# Developer sandbox Dockerfile lives at: -# developer/docker/Dockerfile +# Maintainer sandbox Dockerfile lives at: +# docker/Dockerfile # # The root Dockerfile intentionally delegates to the published sandbox image so # accidental root builds behave like normal skill installs. diff --git a/README.md b/README.md index d413d06..fc9ac4f 100644 --- a/README.md +++ b/README.md @@ -161,8 +161,7 @@ Run `openghost help` for the complete command list. |-- AGENTS.md |-- Dockerfile |-- README.md -|-- developer/ -| `-- docker/ +|-- docker/ |-- openghost |-- runtime/ `-- skills/ @@ -186,7 +185,7 @@ Important paths: - `skills/openghost-skill/scripts/openghost.sh` - canonical launcher and Docker sandbox implementation. - `skills/openghost-skill/scripts/pentest/` - bundled reusable script templates. - `skills/openghost-skill/assets/` - scope, auth, finding, and report templates. -- `developer/docker/Dockerfile` - maintainer image source for the sandbox. +- `docker/Dockerfile` - maintainer image source for the sandbox. - `Dockerfile` - published-image delegate for normal users. ## Agent Skill Structure @@ -252,7 +251,7 @@ For sandbox/runtime changes: ### Add or update a sandbox tool -1. Install the tool in `developer/docker/Dockerfile`. +1. Install the tool in `docker/Dockerfile`. 2. Add it to `ALLOWED_TOOLS` in `skills/openghost-skill/scripts/openghost.sh` if agents should run it directly. 3. Add it to `skills/openghost-skill/scripts/verify-toolchain.sh` if it is required. 4. Document operator usage in `SKILL.md`, `references/tooling.md`, or the relevant module file. @@ -290,7 +289,7 @@ The project is installable by skill managers that can read GitHub repositories w - Avoid duplicating long methodology in both `SKILL.md` and `references/`. - Keep scripts, references, and assets organized by purpose. -The sandbox image is built from `developer/docker/Dockerfile` by the GitHub Actions workflow in `.github/workflows/publish-sandbox-image.yml`. +The sandbox image is built from `docker/Dockerfile` by the GitHub Actions workflow in `.github/workflows/publish-sandbox-image.yml`. ## License diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..dd33d2e --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,40 @@ +# Security Policy + +OpenGhost is security tooling, so vulnerability reports need enough detail to reproduce safely without exposing targets or third-party systems. + +## Supported Versions + +Security fixes are handled on the `main` branch until the project publishes versioned releases. + +## Reporting a Vulnerability + +Use GitHub private vulnerability reporting for this repository when available. Do not open a public issue with exploit details, credentials, target data, or sensitive evidence. + +Include: + +- Affected commit, release, or sandbox image digest. +- Reproduction steps using only local fixtures, disposable labs, or intentionally vulnerable targets. +- Expected and actual behavior. +- Impact and any safe proof-of-concept output. +- Whether any secret, credential, customer data, or third-party target was involved. + +If private vulnerability reporting is not available, open a public issue that says a private security report is needed, but do not include exploit details. + +## Scope + +In scope: + +- OpenGhost launcher and engagement-state helpers. +- Skill instructions, bundled scripts, references, and templates. +- Published sandbox image build configuration. +- CI/CD configuration in this repository. + +Out of scope: + +- Findings in third-party systems tested with OpenGhost. +- Vulnerabilities in upstream security tools unless OpenGhost packages or invokes them unsafely. +- Reports that require destructive testing outside an authorized lab. + +## Disclosure + +Maintainers will acknowledge valid reports, triage impact, and publish fixes or mitigations before public disclosure when practical. Reporters should avoid accessing data beyond the minimum proof needed and should delete any sensitive evidence after resolution unless legal or contractual obligations require retention. diff --git a/developer/docker/Dockerfile b/docker/Dockerfile similarity index 100% rename from developer/docker/Dockerfile rename to docker/Dockerfile diff --git a/developer/docker/healthcheck.sh b/docker/healthcheck.sh similarity index 100% rename from developer/docker/healthcheck.sh rename to docker/healthcheck.sh diff --git a/skills/openghost-skill/references/tooling.md b/skills/openghost-skill/references/tooling.md index 0eff028..3202bf1 100644 --- a/skills/openghost-skill/references/tooling.md +++ b/skills/openghost-skill/references/tooling.md @@ -22,7 +22,7 @@ openghost sandbox update openghost sandbox shell ``` -The launcher pulls `ghcr.io/vaibhavsing/openghost-sandbox:latest` by default when the image is missing. Set `OPENGHOST_IMAGE` to override the image. Normal skill users should not build a Dockerfile locally; maintainers build and publish the sandbox from the repo's developer-only Docker context. +The launcher pulls `ghcr.io/vaibhavsing/openghost-sandbox:latest` by default when the image is missing. Set `OPENGHOST_IMAGE` to override the image. Normal skill users should not build a Dockerfile locally; maintainers build and publish the sandbox from the repo's Docker context. ## Execution Commands @@ -106,8 +106,8 @@ Developer-only local image builds are explicit opt-in: ```bash OPENGHOST_BUILD=1 \ OPENGHOST_IMAGE=openghost-sandbox:dev \ - OPENGHOST_DOCKERFILE=developer/docker/Dockerfile \ - OPENGHOST_BUILD_CONTEXT=developer/docker \ + OPENGHOST_DOCKERFILE=docker/Dockerfile \ + OPENGHOST_BUILD_CONTEXT=docker \ openghost sandbox start ``` diff --git a/skills/openghost-skill/scripts/__pycache__/select-modules.cpython-312.pyc b/skills/openghost-skill/scripts/__pycache__/select-modules.cpython-312.pyc deleted file mode 100644 index 42e411258dbafd1198a76b75a06bf5ddf98fb8c8..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 4725 zcma)A-ES1v6`$Fi-P!NOUl<$5Sw8CxEG7+UOF}6jKtl^A$Y6>wSTM^)(Dm$06UZ`0)Vpj|Wj0i9Z#_Lnwj*(1uYI1)+^7 zQ52dS;y4`ja7qk*k$Wuk+$O?qs>gk{@7S<;b;BnY4fR1=BEyUC=gX=E6}r|0qpp($r# zn8;W)DH$eC0#dDD?=s6c2tcQbLx;Q!Rh3%^$LHf6i|e{)PQ4qd9-ZIw-MKx7X7?Ow z>^btz-nsDLY8f%d zb%VllW%x_-EV+KkgmoZTuTP~)k=VYAl2&pTiz9%y0}?`M12T#`VYnWCWFu5nZeEPc z9G(^X<^$1dkt>mz)1L%3KJ;>dejEk448Nr!LeI(iD}Lr`JKu%n3u>t&{=Ua`b{clb znpyTD;lA%)3(Y@G%kSEGs)qP~H3CRL!TX_mt-bhEOJO**(VPcG?#EW>vbC=&?jD}z zQM|zR$EpH5+j-}#oTeq! zm2A^8S!9j%ZEnk#ubb|4SJ#%qncn5jwp$c&xW^_6XSP}BOKz{Q$L+OS$VJ!vEv{Af ztiWeyYumz8-g`b*+ie+21|}tYroB^Ka@$B{yGwCaet=ig9L8jj()=m|m8tkrsS?&O ze0~_o5s{LWN*b+*sg%QOD*jZ8QJP91m1+{A%JZ)q#i9fp$CNM-0F*E?M8OxK(^N=$ zFndATLSE5KhRYhbC{bG|5JR_x7LO3+yrIepadaQ^p~w8r%HfI35L31?ii8zxQDaik zE!i+8RmGA_^;{~QIRCv#rED3@C#x_;Eo^8YLq%1$O5jFvB2#$*%q*KOO1hK-YfNnA z;3G~g#`_%Iuh@sOvKIhg-eTN^wPZ@lF+>haX8wX^0b3-7JgHEN7?NpSDry#63wzcP z*X5F_84|M8A|rPUkq5UeS<*&M#B;<09N3k zFeJrNE~hb;2f()gXiDWGFkuVe@}yCsmcx-PRlf+#2cizUKz=Qm`2o5{$ux9p z%D|IZ&6u(=wQ(OXmnlVZ`l5n{a%V1*)Hb=@dAgbj`Fi)wOQcz9-QHiKJ^G`E!s?3<7 zssoLum~EWoMj(MW2YDrm9eWMuN^Ie8vLUu3j2?p2nX^NV5*ve;1w++sFFSUO0*$r>4G6g%Ir!S>;q>tnhfW_mJZcLW!_aIGR%}0k zVm<2~+_c`R$j;L_g0k@p>+mRzjM_xPDvS9mL=hJ6m(87$U*gjM$nj{&u z{f^%loMWB`@=}>l*mdk0fGHkkx?+pdGbu?si-;BB9ip0=l4j=+lHf=nry)yNK8trcfZs8Xfy3{kZ!t{eSHL^T0dkTH#9J=h|E>F&j&K65Cvhj#ZC9^<}K{#=d$iQT_g6 zyz9onn@6u7tqo>td9&Vqp&rN8Hx_#~yw`cB|8{?E>&e>axq9D3z2|&Q%FOm;sw0bl z{^rfS*Z0<*J6k&^*SkUFi2P-~NtqnO( z7`#yL!!=?3VmEt4-|fEImh-iAuHKigcdOOoi(S3%dF}*n2Oo0WmO~z>k9bBraC7TB z!RqceJ=J5Mi}A(4x|!Zu|8OI)+v(og)d(aP#Q637Ey)Xwz>WnmHnV-MbK7j^wg=mf zH#$d}ssMUnLF||ro9h{x?HPKIJk{tq-Gc3D1YTYc`)>beg_-Uqa7QDseL?KH{^MoB zFNMfEXKrW>VasP?_-B`Ya(O2EKpa>MM6Wu*ztwxUqY(q(&WC<368*QA3&tQV>J{~t z2nlEeHqD14|NYnNJQq8|6Lwkri0e7FLHKBW0%|*uPO~kWPA3J-t}~SoobH5`7%_A> z#2Ef}fZ_E3b4fpD*OW?-9s6@IaUOTT7>}^(I8?U4Fz~^323|P6$+#`1)5wt1X*-lo zXG>sANvAQpq~UL{ik)x#Ee00ZRbEpw&TStv!h&CAm2)v?Hz4OwF?V(N1Tll7aQc Date: Wed, 3 Jun 2026 22:57:52 +0530 Subject: [PATCH 2/2] Improve OpenGhost documentation --- AGENTS.md | 164 ++++++++++++++++++++++++++++ ARCHITECTURE.md | 208 ++++++++++++++++++++++++++++++++++++ CONTRIBUTING.md | 70 ++++-------- DEVELOPMENT.md | 143 +++++++++++++++++++++++++ README.md | 278 +++++++++++++++++------------------------------- 5 files changed, 631 insertions(+), 232 deletions(-) create mode 100644 AGENTS.md create mode 100644 ARCHITECTURE.md create mode 100644 DEVELOPMENT.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..1525c77 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,164 @@ +# AGENTS.md + +Project context for coding agents working on OpenGhost. + +## What This Repo Is + +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. + +The central design constraint is simple: agents provide reasoning and workflow control, while OpenGhost provides the sandboxed execution layer and structured engagement state. + +## Product Boundary + +- This repository owns the OpenGhost skill package and sandbox launcher. +- Security tools must be executed through `openghost`, not directly on the host. +- External research/reference directories are not runtime dependencies and should not be cited as OpenGhost source material. +- Generated engagement data belongs under `.openghost/` and should normally stay uncommitted. + +## Agent Skill Structure + +OpenGhost follows the standard Agent Skill layout: + +- `skills/openghost-skill/SKILL.md` is the published skill entrypoint and operator workflow. +- Keep `SKILL.md` focused and use progressive disclosure: short entrypoint instructions first, deeper details in references. +- `skills/openghost-skill/references/` contains deeper guidance that agents should load only when relevant. +- `skills/openghost-skill/scripts/` contains deterministic helpers and launcher implementation. +- `skills/openghost-skill/assets/` contains templates and reusable output files. +- Do not duplicate large methodology content across files; link to the canonical reference instead. + +## Main Source Paths + +- `skills/openghost-skill/SKILL.md` - published skill entrypoint and operator workflow. +- `skills/openghost-skill/references/` - deeper guidance for modules, reporting, tooling, auth, and workflow. +- `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. +- `skills/openghost-skill/scripts/openghost.sh` - canonical CLI and Docker sandbox implementation. +- `skills/openghost-skill/scripts/verify-toolchain.sh` - runtime toolchain verification. +- `skills/openghost-skill/scripts/select-modules.py` - module selection helper. +- `skills/openghost-skill/assets/` - templates for scope, auth, findings, and reports. +- `skills/openghost-skill/agents/` - compatibility notes for other coding agents. + +## Launchers + +There are three launcher entrypoints: + +- `./openghost` forwards to `skills/openghost`. +- `skills/openghost` forwards to `skills/openghost-skill/scripts/openghost.sh`. +- `skills/openghost-skill/openghost` is the standalone fallback for installs that copy only the skill package. + +Keep launcher behavior consistent when changing CLI commands. + +## Sandbox Model + +The root `Dockerfile` intentionally delegates to `ghcr.io/vaibhavsing/openghost-sandbox:latest`. The actual maintainer image source is `docker/Dockerfile`. + +Normal users should pull the published image. Maintainers can set `OPENGHOST_BUILD=1` to build from `docker/`. + +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`. + +## CLI Surface + +Primary commands: + +```bash +./openghost sandbox start +./openghost sandbox status +./openghost sandbox stop +./openghost sandbox update +./openghost run [args...] +./openghost bash '' +./openghost python code '