From fb012249d36f8456a833ca403a2ee980db1fd04d Mon Sep 17 00:00:00 2001 From: dstours Date: Fri, 17 Jul 2026 18:39:55 -0400 Subject: [PATCH] Polish and complete documentation --- .github/workflows/pages.yml | 2 +- README.md | 16 +- docs-site/index.html | 2 +- docs-site/src/App.tsx | 72 ++++++- docs/ARCHITECTURE.md | 137 +++++++++++++ docs/CHANNELS.md | 203 ++++++++++++++++++++ docs/CLI.md | 240 +++++++++++++++++++++++ docs/CONFIGURATION.md | 247 ++++++++++++++++++++++++ docs/DEVELOPMENT.md | 152 +++++++++++++++ docs/GITHUB_SETUP.md | 156 +++++++++++++++ docs/INSTALLATION.md | 173 +++++++++++++++++ docs/QUICKSTART.md | 319 +++++++++++++++++-------------- docs/README.md | 167 +++++++++------- docs/TROUBLESHOOTING.md | 186 ++++++++++++++++++ scripts/check-doc-consistency.ts | 8 + 15 files changed, 1848 insertions(+), 232 deletions(-) create mode 100644 docs/ARCHITECTURE.md create mode 100644 docs/CHANNELS.md create mode 100644 docs/CLI.md create mode 100644 docs/CONFIGURATION.md create mode 100644 docs/DEVELOPMENT.md create mode 100644 docs/GITHUB_SETUP.md create mode 100644 docs/INSTALLATION.md create mode 100644 docs/TROUBLESHOOTING.md diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml index 5b62fef..cb7d122 100644 --- a/.github/workflows/pages.yml +++ b/.github/workflows/pages.yml @@ -1,4 +1,4 @@ -name: Deploy experimental docs to GitHub Pages +name: Deploy docs to GitHub Pages on: push: diff --git a/README.md b/README.md index 7f22d1c..8ecf6df 100644 --- a/README.md +++ b/README.md @@ -9,7 +9,7 @@

- A GitHub-native, encrypted control plane for authorized systems research. + GitHub-native command-and-control for authorized security research, with encrypted multi-channel transport and resilient failover.

> [!IMPORTANT] @@ -21,15 +21,25 @@ OctoC2 combines a TypeScript beacon, durable controller, local operator dashboard, and CLI. GitHub-backed and direct transports share one signed task protocol, one identity model, and the same result-ownership rules. +**Documentation:** [Browse the complete manual](docs/README.md) or open the +[documentation site](https://dstours.github.io/OctoC2/). + ## Start here | I want to… | Read or run | |---|---| | Browse all documentation | [Documentation index](docs/README.md) | -| Understand the system | [Architecture](#architecture) | -| Set up a local environment | [Local evaluation quickstart](docs/QUICKSTART.md) | +| Understand the system | [Architecture guide](docs/ARCHITECTURE.md) | +| Install the toolchain and binaries | [Installation](docs/INSTALLATION.md) | +| Configure the GitHub App, repos, and PATs | [GitHub setup](docs/GITHUB_SETUP.md) | +| Complete a first local run | [Quickstart](docs/QUICKSTART.md) | +| Configure every channel | [Channel guide](docs/CHANNELS.md) | +| Use operator commands | [CLI reference](docs/CLI.md) | +| Look up an environment variable | [Configuration reference](docs/CONFIGURATION.md) | | Configure listeners and certificates | [Operations and assurance](docs/PRODUCTION.md) | | Configure GitHub App recovery | [Recovery guide](docs/RECOVERY.md) | +| Diagnose a failure | [Troubleshooting](docs/TROUBLESHOOTING.md) | +| Contribute a change | [Development guide](docs/DEVELOPMENT.md) | | Review implementation and live evidence | [Verification traceability](docs/REMEDIATION_TRACEABILITY.md) | | Use the dashboard | [Dashboard guide](dashboard/README.md) | diff --git a/docs-site/index.html b/docs-site/index.html index 878690b..4cce84b 100644 --- a/docs-site/index.html +++ b/docs-site/index.html @@ -5,7 +5,7 @@ OctoC2 — Documentation - +
diff --git a/docs-site/src/App.tsx b/docs-site/src/App.tsx index 97e9db4..5465184 100644 --- a/docs-site/src/App.tsx +++ b/docs-site/src/App.tsx @@ -1,6 +1,6 @@ import { useState } from 'react' -const owner = import.meta.env.VITE_GITHUB_OWNER || 'octoc2' +const owner = import.meta.env.VITE_GITHUB_OWNER || 'dstours' const repo = import.meta.env.VITE_GITHUB_REPO || 'OctoC2' const repositoryUrl = `https://github.com/${owner}/${repo}` const docsUrl = (path: string) => `${repositoryUrl}/blob/main/${path}` @@ -76,11 +76,47 @@ const transportGroups = [ ] const guides = [ + { + title: 'Installation', + description: 'Install the pinned toolchain, run each component, and build platform beacon binaries.', + href: docsUrl('docs/INSTALLATION.md'), + label: 'Install', + }, + { + title: 'GitHub setup', + description: 'Configure repositories, the GitHub App, least-privilege permissions, PAT roles, and rotation.', + href: docsUrl('docs/GITHUB_SETUP.md'), + label: 'Provision', + }, { title: 'Quickstart', - description: 'Install, configure role-separated credentials, and launch the local stack.', + description: 'Build and import a pre-enrolled beacon, then verify an accepted ping result.', href: docsUrl('docs/QUICKSTART.md'), - label: 'Start here', + label: 'First run', + }, + { + title: 'Architecture', + description: 'Understand components, identity boundaries, task lifecycle, durable state, and recovery.', + href: docsUrl('docs/ARCHITECTURE.md'), + label: 'Learn', + }, + { + title: 'Channel guide', + description: 'Compare every transport, permission, prerequisite, priority rule, and qualification step.', + href: docsUrl('docs/CHANNELS.md'), + label: 'Transports', + }, + { + title: 'Configuration', + description: 'Look up controller, listener, beacon, OIDC, recovery, dashboard, and CLI settings.', + href: docsUrl('docs/CONFIGURATION.md'), + label: 'Reference', + }, + { + title: 'CLI reference', + description: 'Use setup, enrollment, builds, inventory, tasks, results, proxy, and service commands.', + href: docsUrl('docs/CLI.md'), + label: 'Operate', }, { title: 'Operations & assurance', @@ -94,6 +130,18 @@ const guides = [ href: docsUrl('docs/RECOVERY.md'), label: 'Configure recovery', }, + { + title: 'Troubleshooting', + description: 'Diagnose GitHub errors, decrypt failures, acknowledgements, proxy, TLS, gRPC, OIDC, and state.', + href: docsUrl('docs/TROUBLESHOOTING.md'), + label: 'Diagnose', + }, + { + title: 'Development', + description: 'Work with shared contracts, tests, builds, generated protocol bindings, and change checks.', + href: docsUrl('docs/DEVELOPMENT.md'), + label: 'Contribute', + }, { title: 'Verification evidence', description: 'Trace implementation decisions to tests, live qualifications, and cleanup records.', @@ -178,6 +226,7 @@ function App() { Quickstart Transports Security + Guides GitHub @@ -194,11 +243,12 @@ function App() {
@@ -366,8 +416,8 @@ function App() {
{guides.map((guide) => ( @@ -385,12 +435,14 @@ function App() {