Merge pull request #9 from initstring/docs

docs: Revamp docs and add screenshots

Author: initstring

README.md

@@ -10,89 +10,26 @@ TTPx is a platform for internal Red Teams to plan and analyze their operations.
 - Deep integration into MITRE ATT&CK and STIX 2.1 standards - including importing attack campaigns and threat actor profiles directly from MITRE or from other STIX-based threat intelligence sources.
 - RBAC with group restrictions, allowing teams to work on operation planning in stealth before providing visibility to other platform users.
 
-## Contributing
+![Dashboard screenshot](docs/images/dashboard.png)
+
+## Docs
 
-See `AGENTS.md` for engineering standards.
+User Docs:
+- [Installation](docs/installation.md)
+- [Getting Started Workflow](docs/getting-started.md)
 
-Docs
-- UI Style Guide: `docs/dev/STYLE.md`
-- Design Overview: `docs/dev/DESIGN.md`
+Development Docs:
+- [UI Style Guide](docs/dev/STYLE.md)
+- [Design Overview](docs/dev/DESIGN.md)
+
+## Contributing
 
 Not currently accepting pull requests - still just an experiment.
 
+See [AGENTS.md](AGENTS.md) for engineering standards.
+
 ## Tech Stack
 
 Initially based on the T3 Stack - Next.js, tRPC, Prisma, TypeScript. Type-safe APIs, server-side rendering, and component-driven design.
 
 Local development uses sqlite and the node server. "Production" installation uses docker-compose, postgres, and BYO-reverse-proxy.
-
-## Getting Started
-
-### Local Development (Non-Docker)
-
-Local development uses sqlite and the node dev server.
-
-```sh
-# Copy example env file and replace secrets
-cp .env.example .env
-
-# Install dependencies
-npm install
-
-# Initialize schema and seed first-run admin + MITRE
-npm run init
-
-# Optionally - seed demo taxonomy/operation data
-npx tsx scripts/demo-data.ts
-
-# Start development server (or use one-liner: `npm run dev:with-init`)
-npm run dev --turbo
-```
-
-### Production (Docker)
-
-The provided `docker-compose.yml` file does not include a reverse proxy as you'd likely want to configure your own with TLS.
-
-```sh
-cd deploy/docker
-
-# Copy example env file and replace secrets
-cp .env.example .env
-
-docker compose up -d
-
-# Destroy all data and start from scratch - WARNING YOU WILL LOSE YOUR DB
-docker compose down
-docker system prune -a --volumes
-```
-
-Notes:
-
-- First login forces a password change.
-
-### Logging
-
-- Server logs are emitted to stdout/stderr (structured JSON in production, pretty in dev). Rely on Docker and the host OS for collection and rotation.
-- Log level defaults: `debug` in development, `info` in production. Override with `LOG_LEVEL`.
-
-### Single Sign-On (SSO)
-
-SSO is available via environment variable configuration. Users must be provisioned first - they will NOT be auto-created when an SSO login occurs.
-
-For a pure-SSO environment, the INITIAL_ADMIN_EMAIL can be set to something from the SSO provider, and password authentication can be disabled completely.
-
-Environment variables:
-
-```
-# Toggle credentials provider (default: enabled)
-AUTH_CREDENTIALS_ENABLED=true
-
-# Register Google provider when present (optional)
-GOOGLE_CLIENT_ID=
-GOOGLE_CLIENT_SECRET=
-```
-
-For Google, set the following:
-
-- Authorized JavaScript origins: Should match `AUTH_URL` from .env
-- Authorized redirect URIs: `AUTH_URL` + `/api/auth/callback/google`

docs/getting-started.md

@@ -0,0 +1,124 @@
+# Getting Started with TTPx
+
+This guide walks through the first workflow after you launch the application. Follow the steps in order so operations have the context they need for accurate analytics. The README already covers installing dependencies and starting the app.
+
+## 1. Prepare Your Taxonomy
+
+- Open Settings -> Taxonomy and customize each section to your liking.
+- Required to record defensive outcomes:
+  - Tool categories. Examples: EDR, SIEM, IDS, IPS, etc. You may wish to include "Human Being" to capture manual responses.
+  - Tools. Examples: CrowdStrike Falcon, Splunk, Metasploit, Sliver, etc. These are classified as defensive or offensive. Offensive tools are optional but defensive tools are required for recording detection and prevention outcomes.
+  - Log Sources. Examples: Sysmon, Windows Event Logs, etc. These are used for recording attribution outcomes.
+- Optional:
+  - Threat Actors. You can enter them manually or use the import option to pull in techniques directly from MITRE ATT&CK.
+  - Crown Jewels. Examples: Production DB, Source Code Repo, etc.
+  - Tags. Examples: Stealth, Purple Team, etc. These can be applied to operations and used for filtering lists analytics.
+
+<p align="center">
+  <a href="images/taxonomy.png">
+    <img src="images/taxonomy.png" width="540" alt="Screenshot - Taxonomy" />
+  </a>
+</p>
+
+## 2. Add Users and Groups
+
+- Go to Settings -> Users to create additional logins.
+- Assign each user the appropriate role:
+  - Admin: Full platform access, including settings
+  - Operator: Read/Write access to operations, view analytics, cannot access settings
+  - Viewer: Read access to operations and analytics, cannot access settings
+- Create groups under Settings -> Groups if you plan to restrict operations to specific teams.
+- When SSO is enabled, every user still needs to exist in TTPx ahead of time with the correct role and group membership.
+
+## 3. Create an Operation
+
+- Navigate to Operations and click New.
+  - Blank operation: create from scratch
+  - From threat actor: imports the techniques from taxonomy definitions of threat actors
+  - From MITRE campaign: imports the techniques from a MITRE ATT&CK campaign
+- Provide the name, description, status
+- Set the start and end dates. These dates drive analytics such as trends and duration metrics, so keep them accurate.
+- Optionally, configure tags, crown jewels, threat actor being emulated, and group access restrictions.
+
+<p align="center">
+  <a href="images/new-operation.png">
+    <img src="images/new-operation.png" width="540" alt="Screenshot - New Operation" />
+  </a>
+</p>
+
+## 4. Plan Attack Techniques
+
+- Inside the operation, open the Techniques tab and add a technique. When planning, you only need to fill in the overview. You can come back and add detail as the operation progresses.
+- Overview tab:
+  - Use the Tactic/Technique pickers to choose from the catalog
+  - Fill in an optional description
+- Execution tab:
+  - Timing, execution details, offensive tooling, and crown jewel targeting
+- Outcomes tab:
+  - Was the technique detected, prevented, or attributed later during IR?
+  - What tooling and log sources were involved in successful outcomes or SHOULD HAVE BEEN involved in failed outcomes?
+  - Note: You can leave an outcome as "N/A" and it will not be graded as failed in analytics. Do this for things that realistically cannot be detected/prevented/attributed.
+
+<p align="center">
+  <a href="images/technique-editor.png">
+    <img src="images/technique-editor.png" width="540" alt="Screenshot - Technique Editor" />
+  </a>
+</p>
+
+## 5. Review Attack Visualizations Inside the Operation
+
+### Attack Matrix - Operation View
+
+This view shows an attack matrix specific to the operation. You can maximize the view to fill your browser, expand or hide sub-techniques, and toggle visibility of the operation across the entire ATT&CK matrix.
+
+Success metrics are displayed on each technique card.
+
+<p align="center">
+  <a href="images/operation-matrix.png">
+    <img src="images/operation-matrix.png" width="540" alt="Screenshot - Operation Matrix" />
+  </a>
+</p>
+
+### Attack Flow
+
+This is an interactive flow chart built automatically from the operation's techniques. Because attacks don't always follow a logical order, you can edit this flowchart and save any changes you make. This includes dragging to re-arrange cards, deleting connection points, and creating new ones. You can also click "Reset Layout" to start from the auto-generated chart.
+
+Success metrics are displayed on each technique card.
+
+<p align="center">
+  <a href="images/attack-flow.png">
+    <img src="images/attack-flow.png" width="540" alt="Screenshot - Attack Flow" />
+  </a>
+</p>
+
+## 6. Explore Analytics
+
+- Analytics -> Scorecard for high-level effectiveness metrics. Filters at the top limit results by date range and tags.
+- Analytics -> Attack Matrix to compare executed coverage across all accessible operations. Toggle to view against the complete ATT&CK matrix. Metrics are displayed on each individual technique card.
+- Analytics -> Trends to track performance over time. Filters at the top limit results by date range and tags.
+
+<p align="center">
+  <a href="images/scorecard-1.png">
+    <img src="images/scorecard-1.png" width="540" alt="Screenshot - Score Card 1" />
+  </a>
+</p>
+<p align="center">
+  <a href="images/scorecard-2.png">
+    <img src="images/scorecard-2.png" width="540" alt="Screenshot - Score Card 2" />
+  </a>
+</p>
+<p align="center">
+  <a href="images/scorecard-3.png">
+    <img src="images/scorecard-3.png" width="540" alt="Screenshot - Score Card 3" />
+  </a>
+</p>
+<p align="center">
+  <a href="images/trends-1.png">
+    <img src="images/trends-1.png" width="540" alt="Screenshot - Trends 1" />
+  </a>
+</p>
+<p align="center">
+  <a href="images/trends-2.png">
+    <img src="images/trends-2.png" width="540" alt="Screenshot - Trends 2" />
+  </a>
+</p>