From 2266e0cf90b329f29a9b86314d354e3fe9fad2c8 Mon Sep 17 00:00:00 2001 From: Irlan Cidade <2146925357+icidade@users.noreply.github.com> Date: Sat, 11 Jul 2026 15:28:51 +0000 Subject: [PATCH] docs: simplify readme and define wiki boundary --- README.md | 107 ++++++++++++++++-------------- docs/readme-docs-wiki-boundary.md | 62 +++++++++++++++++ 2 files changed, 121 insertions(+), 48 deletions(-) create mode 100644 docs/readme-docs-wiki-boundary.md diff --git a/README.md b/README.md index 58283cd..dcaceb9 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,16 @@ Agentic security staff for [Hermes Agent](https://github.com/NousResearch/hermes-agent), distributed as a reproducible overlay of profiles, prompts, templates, and operating policies. -> This repository is **not a Hermes fork**. The runtime is installed by the bootstrap from an immutable version and commit declared in [`config/hermes-version.env`](config/hermes-version.env). +> This repository is **not a Hermes fork**. MiniCISO is a public overlay installed on top of a Hermes runtime pinned by version and commit in [`config/hermes-version.env`](config/hermes-version.env). + +## Why MiniCISO + +MiniCISO packages a reusable security operating model around Hermes: +- a `chief-of-staff` coordinator for intake, routing, synthesis, and QA enforcement; +- specialized security SMEs for threat modeling, architecture, code review, AppSec, compliance, offensive validation, recon, and QA; +- evidence-driven workflows with explicit gates for finding validation and post-submission follow-up. + +It is designed to help a human operator run structured security engagements more consistently. It does **not** replace human authorization, judgment, or accountable decision-making. ## Quick restore @@ -22,20 +31,14 @@ cd miniCISO ./scripts/bootstrap.sh ``` -The bootstrap: - -1. downloads the official Hermes installer from the pinned commit and validates its SHA-256; -2. installs the runtime without writing secrets into the repository; -3. runs local provider/model setup; -4. creates the nine MiniCISO profiles from the local configuration; -5. installs each `SOUL.md`, creates the shared workspace, and configures the local terminal; -6. runs structural checks. +The bootstrap restores the pinned Hermes runtime, creates the MiniCISO profile set, installs the overlay prompts and templates, prepares the shared workspace, and runs structural checks. -Credentials requested by `hermes setup` remain in the user's Hermes environment. They are never copied into this repository. +Credentials requested by `hermes setup` stay in the user's Hermes environment. They are never copied into this repository. -## Profiles +## Security staff at a glance -- `chief-of-staff`: MiniCISO coordinator and final synthesis +MiniCISO ships the following public profile set: +- `chief-of-staff` - `security-threat-modeling` - `security-architecture` - `security-code-review` @@ -43,13 +46,13 @@ Credentials requested by `hermes setup` remain in the user's Hermes environment. - `security-compliance-mapper` - `security-offensive-security` - `security-recon-attack-surface-strategist` -- `security-qa`: final quality gate +- `security-qa` -`chief-of-staff` is a dedicated Hermes profile fully managed by this overlay. The bootstrap does not modify the default Hermes profile prompt. +For responsibilities, handoffs, and usage examples, see the wiki staff guide and the canonical profile contract in [`docs/profile-setup.md`](docs/profile-setup.md). -## Validation +## Validate the installation -Offline tree validation: +Offline repository validation: ```powershell .\scripts\validate-repo.ps1 @@ -59,58 +62,66 @@ Offline tree validation: ./scripts/validate-repo.sh ``` -After bootstrap, validate the runtime: +Runtime smoke test after bootstrap: ```powershell .\scripts\smoke-test.ps1 ``` -Use `-Online`/`--online` to also send a short question to each profile. That mode consumes the configured provider. +```bash +./scripts/smoke-test.sh +``` + +Use `-Online` / `--online` only when you want to send a real question to each profile using the configured provider. ## Security and privacy -The repo contains only non-secret configuration and sanitized content. Do not publish `.env`, tokens, sessions, memories, logs, or real reports. See [`SECURITY.md`](SECURITY.md) and [`.env.example`](.env.example). +This repository contains only non-secret configuration and sanitized public content. Do **not** publish `.env` files, tokens, sessions, memories, logs, real reports, or unsanitized evidence. See [`SECURITY.md`](SECURITY.md) and [`.env.example`](.env.example). -## Safe overlay self-update +## External finding workflow -The repo can now maintain a public, sanitized copy of what is running on the VPS without publishing private state. +For external vulnerability or bug bounty work, report drafting starts only after a `GO` decision. `RESEARCH` means produce an impact-validation plan, and `NO-GO` means block submission and capture the lesson learned. -Key additional public artifacts: +Canonical sources: +- [`docs/kag-finding-validation.md`](docs/kag-finding-validation.md) +- [`templates/finding-decision-template.md`](templates/finding-decision-template.md) +- [`docs/submission-followup.md`](docs/submission-followup.md) +- [`templates/submission-followup-template.md`](templates/submission-followup-template.md) -- `tools/headroom_phase1/`: indexer, KAG query builder, selector, and Headroom Phase 1.1A wrapper -- `config/chief-of-staff.public.yaml`: sanitized snapshot of the main profile's non-secret configuration -- `scripts/export_safe_self_state.py`: safe export of public state into the repo +## Safe overlay self-update -Quick flow: +MiniCISO can maintain a public, sanitized copy of selected runtime-safe artifacts without publishing private state. See [`docs/self-update-capability.md`](docs/self-update-capability.md). -```bash -python3 scripts/export_safe_self_state.py --apply -./scripts/validate-repo.sh -``` +## Documentation map -## External finding workflow +### Start here +- [Project Wiki](https://github.com/icidade/miniCISO/wiki) +- [Installation Guide](INSTALL.md) +- [Security Policy](SECURITY.md) -For bug bounty / external vulnerability work: +### Getting started +- [Installation and restoration](INSTALL.md) +- [Profile setup contract](docs/profile-setup.md) +- [README vs docs vs Wiki](docs/readme-docs-wiki-boundary.md) -- no external report draft should start before a `GO` decision; -- `RESEARCH` means produce a safe impact-validation plan, not a submission draft; -- `NO-GO` means block submission and register the lesson learned. +### Architecture and operating model +- [Staff operating model](docs/staff-operating-model.md) +- [Repo architecture](docs/repo-architecture.md) +- [Repo mapping](docs/repo-mapping.md) +- [Headroom + KAG selective retrieval](docs/headroom-kag-selective-retrieval.md) -See [`docs/kag-finding-validation.md`](docs/kag-finding-validation.md), [`templates/finding-decision-template.md`](templates/finding-decision-template.md), [`docs/submission-followup.md`](docs/submission-followup.md), and [`templates/submission-followup-template.md`](templates/submission-followup-template.md). +### Finding validation and follow-up +- [KAG-oriented finding validation](docs/kag-finding-validation.md) +- [External submission follow-up](docs/submission-followup.md) -## Documentation +### Operations +- [Dependencies and configuration](docs/dependencies-and-configuration.md) +- [Safe self-update capability](docs/self-update-capability.md) +- [GitHub PR access from the VPS](docs/github-pr-access.md) -- [`INSTALL.md`](INSTALL.md): installation, updates, rollback, and limitations -- [`docs/staff-operating-model.md`](docs/staff-operating-model.md): operating flow -- [`docs/profile-setup.md`](docs/profile-setup.md): profile contract -- [`docs/dependencies-and-configuration.md`](docs/dependencies-and-configuration.md): optional dependencies -- [`docs/headroom-kag-selective-retrieval.md`](docs/headroom-kag-selective-retrieval.md): public architecture for the Headroom + KAG track -- [`docs/kag-finding-validation.md`](docs/kag-finding-validation.md): pre-submission KAG gate for finding validation -- [`docs/submission-followup.md`](docs/submission-followup.md): post-submission follow-up tracking and triage-response workflow -- [`docs/self-update-capability.md`](docs/self-update-capability.md): public export/sync capability -- [`docs/github-pr-access.md`](docs/github-pr-access.md): minimal PAT and credential setup on the VPS -- [`miniciso-staff-service-catalog-v5.md`](miniciso-staff-service-catalog-v5.md): service catalog source -- [`miniciso-staff-service-catalog-v5-full.pdf`](miniciso-staff-service-catalog-v5-full.pdf): service catalog PDF +### Reference artifacts +- [Service catalog source](miniciso-staff-service-catalog-v5.md) +- [Service catalog PDF](miniciso-staff-service-catalog-v5-full.pdf) ## License diff --git a/docs/readme-docs-wiki-boundary.md b/docs/readme-docs-wiki-boundary.md new file mode 100644 index 0000000..b6b635d --- /dev/null +++ b/docs/readme-docs-wiki-boundary.md @@ -0,0 +1,62 @@ +# README vs docs vs Wiki + +This project uses three public documentation layers with different jobs. + +## README + +The `README.md` is the technical landing page. + +It should stay short and discovery-oriented: +- what MiniCISO is; +- what it is not; +- quick restore; +- essential validation and smoke-test commands; +- high-signal links into the rest of the documentation. + +The README should not become the full manual. + +## docs/ + +The `docs/` directory contains canonical, versioned project documents that must evolve with the implementation. + +Examples: +- operating model; +- profile contract; +- installation and runtime constraints; +- KAG/finding-validation rules; +- self-update policy; +- follow-up workflows. + +When a statement is normative, implementation-coupled, or should be reviewed in PRs alongside code/config changes, it belongs in `docs/`. + +## Wiki + +The GitHub Wiki is the editorial and explanatory layer. + +It should: +- explain concepts; +- connect documents into guided reading paths; +- provide human-friendly architecture narratives; +- document playbooks and troubleshooting; +- offer sanitized examples. + +The wiki should not duplicate canonical documents line by line. Instead, wiki pages should explain and link back to the source of truth. + +Recommended note: + +> This page is explanatory. The canonical specification is maintained in `docs/...`. + +## Practical rule + +- **Normative and version-sensitive** -> repository (`README.md`, `docs/`, templates, scripts) +- **Explanatory and navigational** -> wiki +- **Private or operational state** -> never publish in either location + +## Public-content guardrails + +Do not publish: +- secrets or tokens; +- internal hostnames or private URLs; +- sessions, memories, or local logs; +- real client evidence; +- unsanitized reports or triage trails.