docs: Update README for v1.1.0 features

Antigravity · claude · Antigravity · commit 4e4541ed27fc · 2026-02-12T08:40:43.000+01:00
Rewrite README to cover all v1.1.x features: setup wizard, Docker
local runner, multi-CI platform support, severity thresholds, waiver
CLI, HTML reporting, and updated repository structure.

Co-Authored-By: Claude Opus 4.6 &lt;noreply@anthropic.com&gt;
diff --git a/README.md b/README.md
@@ -1,10 +1,10 @@
 # FortressCI: The DevSecOps Platform
 
-FortressCI is a secure-by-default DevSecOps platform blueprint designed to implement "Shift Left" security, automated pipelines, and infrastructure protection. It integrates best-in-class open source security tools to ensure your code and infrastructure are secure from day one.
+FortressCI is a secure-by-default DevSecOps platform blueprint designed to implement "Shift Left" security, automated pipelines, and infrastructure protection. It integrates best-in-class open-source security tools to ensure your code and infrastructure are secure from day one.
 
 > **[View our Roadmap](ROADMAP.md)** for upcoming features and long-term vision.
 
-## 🚀 Features
+## Features
 
 ### Phase 1: Shift Left (Local Development)
 
@@ -16,126 +16,234 @@ Catch issues before they are committed.
 
 ### Phase 2: Automated Pipeline (CI/CD)
 
-Automated checks on every push and pull request via GitHub Actions.
+Automated checks on every push and pull request across **6 CI platforms**.
 
 - **Secret Scanning**: TruffleHog deep scan on git history.
-- **SAST (Static Application Security Testing)**: [Semgrep](https://semgrep.dev/) scans source code for vulnerabilities (OWASP Top 10).
-- **SCA (Software Composition Analysis)**: [Snyk](https://snyk.io/) checks dependencies for known CVEs.
+- **SAST**: [Semgrep](https://semgrep.dev/) scans source code for vulnerabilities (OWASP Top 10).
+- **SCA**: [Snyk](https://snyk.io/) checks dependencies for known CVEs.
+- **IaC Scanning**: Checkov scans Terraform, CloudFormation, and Kubernetes manifests.
+- **Container Security**: [Trivy](https://github.com/aquasecurity/trivy) scans Docker images for OS and library vulnerabilities.
+- **DAST**: [OWASP ZAP](https://www.zaproxy.org/) baseline scan for runtime attack surface.
+- **Signing**: [Cosign](https://github.com/sigstore/cosign) signs container images with SBOM generation.
 
 ### Phase 3: Infrastructure Security
 
-Secure your infrastructure and containers.
-
-- **IaC Scanning**: Checkov scans Terraform, CloudFormation, and Kubernetes manifests.
-- **Container Security**: [Trivy](https://github.com/aquasecurity/trivy) scans Docker images for OS and library vulnerabilities.
+- Container registry signing and attestation
+- SBOM generation via Trivy
+- Compliance audit artifacts
 
 ---
 
-## 🛠️ Getting Started
+## Quick Start
+
+### Option 1: Setup Wizard (Recommended)
 
-### Prerequisites
+```bash
+git clone https://github.com/mackeh/FortressCI.git
+cd FortressCI
 
-- [pre-commit](https://pre-commit.com/#install) installed.
-- [trufflehog](https://github.com/trufflesecurity/trufflehog) installed locally.
-- GitHub Repository with Actions enabled.
+# Run the interactive wizard — detects your project type and CI platform
+./scripts/fortressci-init.sh
 
-### Local Setup (Shift Left)
+# Or skip prompts by specifying the CI platform
+./scripts/fortressci-init.sh --ci github-actions
+```
 
-1.  **Clone the repository:**
+The wizard generates:
+- CI/CD workflow file for your platform
+- `.pre-commit-config.yaml` (local hooks)
+- `.security/waivers.yml` (finding exceptions)
+- `.fortressci.yml` (severity thresholds and scanner config)
 
-    ```bash
-    git clone https://github.com/your-org/FortressCI.git
-    cd FortressCI
-    ```
+Then install the hooks:
 
-2.  **Install Git Hooks:**
+```bash
+pre-commit install
+```
 
-    ```bash
-    pre-commit install
-    ```
+### Option 2: Docker Local Scan
 
-3.  **Test Locally:**
-    Try committing a dummy secret (e.g., `AWS_ACCESS_KEY_ID=AKIA...`) and watch TruffleHog block it.
+Run all security scans locally in a single container:
 
-### CI/CD Setup
+```bash
+# Build the all-in-one scanner image
+docker build -t fortressci/scan .
 
-1.  **Secrets Configuration:**
-    Go to your GitHub Repository > Settings > Secrets and variables > Actions.
-    Add the following secrets:
-    - `SNYK_TOKEN`: Your Snyk API token (get it from [snyk.io](https://app.snyk.io/account)).
+# Scan your project (results output to ./results/)
+docker run --rm \
+  -v $(pwd):/workspace \
+  -v $(pwd)/results:/results \
+  fortressci/scan /workspace
+```
 
-2.  **Run the Pipeline:**
-    Push code to the `main` branch or open a Pull Request. The `DevSecOps Pipeline` workflow will automatically run.
+This runs TruffleHog, Semgrep, Snyk, Checkov, and Trivy in sequence, then generates an interactive HTML report and checks severity thresholds.
 
 ---
 
-## 📂 Repository Structure
+## Supported CI Platforms
 
+| Platform | Template | Generated File |
+|----------|----------|----------------|
+| **GitHub Actions** | `templates/github-actions/devsecops.yml` | `.github/workflows/devsecops.yml` |
+| **GitLab CI** | `templates/gitlab-ci/devsecops.yml` | `.gitlab-ci.yml` |
+| **Bitbucket Pipelines** | `templates/bitbucket/bitbucket-pipelines.yml` | `bitbucket-pipelines.yml` |
+| **Azure Pipelines** | `templates/azure/azure-pipelines.yml` | `azure-pipelines.yml` |
+| **Jenkins** | `templates/jenkins/Jenkinsfile` | `Jenkinsfile` |
+| **CircleCI** | `templates/circleci/config.yml` | `.circleci/config.yml` |
+
+All templates implement the same 5 scan stages with platform-specific syntax.
+
+---
+
+## Severity Thresholds
+
+Configure when your pipeline should fail or warn in `.fortressci.yml`:
+
+```yaml
+thresholds:
+  fail_on: critical   # critical | high | medium | low | none
+  warn_on: high
 ```
-.
-├── .github/workflows/
-│   └── devsecops.yml    # Main CI/CD Pipeline definition
-├── terraform/
-│   └── main.tf          # Sample Terraform file (for testing Checkov)
-├── Dockerfile           # Sample Dockerfile (for testing Trivy)
-├── .pre-commit-config.yaml # Local hook configuration
-└── README.md            # This documentation
+
+Run the gating check manually:
+
+```bash
+./scripts/check-thresholds.sh <results_dir> [.fortressci.yml]
 ```
 
-## 🛡️ Tools & Configuration
+---
 
-| Tool           | Type       | Configuration Context                       |
-| :------------- | :--------- | :------------------------------------------ |
-| **TruffleHog** | Secrets    | `.pre-commit-config.yaml` / `devsecops.yml` |
-| **Semgrep**    | SAST       | `devsecops.yml` (auto-config)               |
-| **Snyk**       | SCA        | `devsecops.yml` (Node/Python/etc.)          |
-| **Checkov**    | IaC        | `.pre-commit-config.yaml` / `devsecops.yml` |
-| **Trivy**      | Containers | `devsecops.yml`                             |
+## Waiver Management
 
-## ⚙️ Operational Reality
+Manage security finding exceptions with the waiver CLI:
 
-To maximize the effectiveness of this platform, we recommend the following operational configurations:
+```bash
+# Add a waiver
+./scripts/fortressci-waiver.sh add \
+  --id "CVE-2024-1234" \
+  --scanner snyk \
+  --severity high \
+  --reason "Dev-dependency only, not used in production" \
+  --expires 2026-06-01 \
+  --author "@your-name"
 
-### 1. Branch Protection
+# List active waivers
+./scripts/fortressci-waiver.sh list
 
-Enable [Branch Protection Rules](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/defining-the-mergeability-of-pull-requests/managing-a-branch-protection-rule) on `main`:
+# List including expired
+./scripts/fortressci-waiver.sh list --expired
+
+# Remove expired waivers
+./scripts/fortressci-waiver.sh expire
+
+# Remove a specific waiver
+./scripts/fortressci-waiver.sh remove --id "CVE-2024-1234"
+```
 
-- **Require status checks to pass before merging**: Select `Secret Scan`, `SAST`, `SCA`, `IaC Scan`, and `Container Scan`.
-- **Require pull request reviews before merging**.
-- **Do not allow bypassing the above settings**.
+Waivers are stored in `.security/waivers.yml` with required fields: `id`, `scanner`, `severity`, `justification`, `expires_on`, `approved_by`.
 
-### 2. Scheduled Scans
+---
+
+## HTML Reporting
+
+After scans complete, an interactive HTML report is generated with:
 
-The pipeline is configured to run a **Baseline Secret Scan** weekly (Sundays at 00:00 UTC). This catches any new vulnerabilities types or historical secrets that might have been added to the scanner rulesets.
+- Severity breakdown cards (critical, high, medium, low)
+- Findings by tool (doughnut chart)
+- Severity distribution (bar chart)
+- Filterable, searchable findings table
+
+Generate manually:
+
+```bash
+python3 scripts/generate-report.py <results_dir>
+```
 
-### 3. Incident Triage
+---
 
-- **Findings**: All findings are output as SARIF and will appear in the **GitHub Security > Code Scanning** tab (if GitHub Advanced Security is enabled) or as downloadable Artifacts.
-- **Waivers**: If a finding is a false positive, verify it locally, then add an entry to [.security/waivers.yml](.security/waivers.yml) with a justification and expiry date, and submit it for review.
+## CI/CD Secrets
 
-## 🔐 V3: Trust & Runtime Security
+Add these to your CI platform's secret store:
 
-### 1. Supply Chain Trust (Cosign)
+| Secret | Required | Purpose |
+|--------|----------|---------|
+| `SNYK_TOKEN` | For SCA scans | [Get token](https://app.snyk.io/account) |
+| `COSIGN_KEY` | For image signing | Generate with `./scripts/generate_keys.sh` |
+| `COSIGN_PASSWORD` | For image signing | Passphrase for Cosign key |
+| `INFRACOST_API_KEY` | For cost estimation | [Get token](https://www.infracost.io/) |
 
-We use [Cosign](https://github.com/sigstore/cosign) to sign container images, proving they were built by this trusted pipeline.
+---
 
-**Setup:**
+## Tools & Configuration
 
-1.  Run the helper script locally to generate keys:
-    ```bash
-    ./scripts/generate_keys.sh
-    ```
-2.  Add the output of `cosign.key` to GitHub Secrets as `COSIGN_PRIVATE_KEY`.
-3.  (Optional) Add `COSIGN_PASSWORD` if you used a passphrase.
+| Tool | Type | Configuration |
+|------|------|---------------|
+| **TruffleHog** | Secrets | `.pre-commit-config.yaml` / CI workflow |
+| **Semgrep** | SAST | CI workflow (auto-config, OWASP Top 10) |
+| **Snyk** | SCA | CI workflow (Node/Python/Go/Java) |
+| **Checkov** | IaC | `.pre-commit-config.yaml` / CI workflow |
+| **Trivy** | Containers | CI workflow |
+| **OWASP ZAP** | DAST | CI workflow (baseline scan) |
+| **Cosign** | Signing | CI workflow (image signing + SBOM) |
 
-### 2. Dynamic Analysis (OWASP ZAP)
+---
 
-A DAST scan attempts to attack the running application in the CI environment.
+## Repository Structure
 
-- **Job**: `dast-scan`
-- **Tools**: OWASP ZAP Baseline Scan.
-- **Artifacts**: HTML Report attached to the workflow run.
+```
+.
+├── .github/
+│   ├── workflows/devsecops.yml    # Primary GitHub Actions pipeline
+│   └── scripts/post_summary.js    # PR comment posting script
+├── .security/
+│   └── waivers.yml                # Security finding exceptions
+├── scripts/
+│   ├── fortressci-init.sh         # Setup wizard CLI
+│   ├── run-all.sh                 # Docker scan orchestrator
+│   ├── generate-report.py         # HTML report generator
+│   ├── summarize.py               # Summary JSON generator
+│   ├── check-thresholds.sh        # Severity threshold gating
+│   ├── fortressci-waiver.sh       # Waiver management CLI
+│   └── generate_keys.sh           # Cosign key generation
+├── templates/                     # CI/CD configs for all 6 platforms
+│   ├── github-actions/
+│   ├── gitlab-ci/
+│   ├── bitbucket/
+│   ├── azure/
+│   ├── jenkins/
+│   ├── circleci/
+│   ├── report.html.j2             # Jinja2 HTML report template
+│   ├── fortressci.yml             # Default threshold config
+│   ├── pre-commit-config.yaml
+│   └── waivers.yml
+├── terraform/main.tf              # Sample (intentionally vulnerable) IaC
+├── .fortressci.yml                # Threshold & scanner configuration
+├── .pre-commit-config.yaml        # Local Git hooks
+├── Dockerfile                     # All-in-one scanner image
+└── Dockerfile.example             # Sample vulnerable Dockerfile
+```
+
+## Operational Recommendations
+
+### Branch Protection
+
+Enable [Branch Protection Rules](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/defining-the-mergeability-of-pull-requests/managing-a-branch-protection-rule) on `main`:
+
+- Require status checks to pass before merging (select all scan jobs).
+- Require pull request reviews before merging.
+- Do not allow bypassing the above settings.
+
+### Scheduled Scans
+
+The GitHub Actions pipeline runs a baseline secret scan weekly (Sundays at 00:00 UTC) to catch newly-identified vulnerability patterns.
+
+### Incident Triage
+
+- **Findings**: All SARIF results appear in GitHub's **Security > Code Scanning** tab (if Advanced Security is enabled) or as downloadable artifacts.
+- **Waivers**: For false positives, use the waiver CLI to document the exception with a justification and expiry date.
+
+---
 
-## 🤝 Contributing
+## Contributing
 
-This is a blueprint repository. Fork it and adapt the `devsecops.yml` to fit your specific build requirements (e.g., usually you would build your application before running the container scan).
+This is a blueprint repository. Fork it and adapt to your needs. Changes to scan logic should be reflected across all 6 CI platform templates.
