jmo-security 0.3.2__tar.gz → 0.4.0__tar.gz

{jmo_security-0.3.2 → jmo_security-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: jmo-security
-Version: 0.3.2
+Version: 0.4.0
 Summary: JMo Security Audit Suite (terminal-first, multi-tool, unified outputs)
 Author-email: James Moceri <general@jmogaming.com>
 License: MIT
@@ -22,9 +22,12 @@ Dynamic: license-file
 </p>
 
 [![Tests](https://github.com/jimmy058910/jmo-security-repo/actions/workflows/tests.yml/badge.svg?branch=main)](https://github.com/jimmy058910/jmo-security-repo/actions/workflows/tests.yml?query=branch%3Amain)
+[![codecov](https://codecov.io/gh/jimmy058910/jmo-security-repo/branch/main/graph/badge.svg)](https://app.codecov.io/gh/jimmy058910/jmo-security-repo)
+[![PyPI - Version](https://img.shields.io/pypi/v/jmo-security)](https://pypi.org/project/jmo-security/)
 [![Website](https://img.shields.io/website?url=https%3A%2F%2Fjmotools.com)](https://jmotools.com)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
-[![Python](https://img.shields.io/badge/Python-%E2%89%A53.8-3776AB?logo=python&logoColor=white)](#)
+[![Python](https://img.shields.io/badge/Python-%E2%89%A53.8-3776AB?logo=python&logoColor=white)](https://www.python.org/)
+
 [![Contributions welcome](https://img.shields.io/badge/Contributions-welcome-brightgreen.svg)](https://github.com/jimmy058910/jmo-security-repo/issues)
 [![Buy me an energy drink](https://img.shields.io/badge/Buy%20me%20an-energy%20drink-%23ff4d00)](https://ko-fi.com/jmogaming)
 
@@ -48,65 +51,173 @@ Project homepage: [jmotools.com](https://jmotools.com)
 
 > Origin story: This started as part of a Cybersecurity Capstone Project. It has since grown into a general-purpose toolkit. I’d love for folks with deeper expertise to jump in—issues and PRs are welcome!
 
-Thinking about contributing? See [CONTRIBUTING.md](CONTRIBUTING.md) for setup, coding standards, and release steps.
+Thinking about contributing? See [CONTRIBUTING.md](CONTRIBUTING.md) for setup and coding standards. For publishing, see [docs/RELEASE.md](docs/RELEASE.md).
 
 Roadmap & history:
-- Completed steps (summary): see [RELEASE_NOTES.md](RELEASE_NOTES.md) → “Roadmap Summary (Steps 1–13)”
+
+- **Latest:** ROADMAP #2 (Interactive Wizard) ✅ Complete - see [docs/examples/wizard-examples.md](docs/examples/wizard-examples.md)
+- Completed steps (summary): see [CHANGELOG.md](CHANGELOG.md) → ROADMAP Items #1-2 and Steps 1–13
 - Active/planned work: see [ROADMAP.md](ROADMAP.md)
 
 For scanning a list of repos from a TSV end-to-end (clone + unshallow + full toolchain), see: [docs/examples/scan_from_tsv.md](docs/examples/scan_from_tsv.md)
 
-## 🧪 New: Simple wrapper commands
+## ✅ CI and release at a glance
+
+- Tests run on a matrix of operating systems and Python versions:
+  - OS: ubuntu-latest, macos-latest
+  - Python: 3.10, 3.11, 3.12
+- CI uses concurrency to cancel redundant runs on rapid pushes and sets a 20-minute job timeout.
+- Coverage is uploaded to Codecov without a token (OIDC/tokenless on public repos) using `codecov/codecov-action@v5`.
+- Releases to PyPI use Trusted Publishers (OIDC) via `pypa/gh-action-pypi-publish@v1`; no PyPI API token is required once the repo is authorized in PyPI.
+
+See `.github/workflows/tests.yml` and `.github/workflows/release.yml` for details.
+
+Quick link: CI Troubleshooting → [Interpreting CI failures](docs/USER_GUIDE.md#interpreting-ci-failures-deeper-guide)
+
+## 🎉 Recent Improvements (Phase 1 - October 2025)
+
+**Security & Bug Fixes:**
+
+- ✅ **XSS vulnerability patched** in HTML dashboard with comprehensive input escaping
+- ✅ **OSV scanner fully integrated** for open-source vulnerability detection
+- ✅ **Type-safe severity enum** with comparison operators for cleaner code
+- ✅ **Backward-compatible suppression keys** (`suppressions` and legacy `suppress`)
+
+**Enhanced Features:**
+
+- 🚀 **Enriched SARIF output** with CWE/OWASP/CVE taxonomies, code snippets, and CVSS scores
+- ⚙️ **Configurable thread recommendations** via `jmo.yml` profiling section
+- 📝 **Magic numbers extracted** to named constants for better maintainability
+- 📚 **9 new roadmap enhancements** including Policy-as-Code (OPA), SLSA attestation, GitHub App, and more
+
+**Quality Metrics:**
+
+- ✅ 100/100 tests passing
+- ✅ 88% code coverage (exceeds 85% requirement)
+- ✅ No breaking changes to existing workflows
+
+See [CHANGELOG.md](CHANGELOG.md) for complete details.
+
+## 🚀 Three Ways to Get Started
+
+### Option 1: 🧙 Interactive Wizard (Recommended for Beginners)
+
+**Never used security scanners before?** Start with the guided wizard:
+
+```bash
+jmotools wizard
+```
+
+The wizard provides:
+
+- ✅ **Step-by-step guidance** through all configuration options
+- ✅ **Profile selection** (fast/balanced/deep) with time estimates
+- ✅ **Docker vs native mode** - zero-installation Docker option!
+- ✅ **Smart target detection** - auto-discovers repositories
+- ✅ **Command preview** - see what will run before executing
+- ✅ **Auto-open results** - dashboard and summary automatically displayed
+
+**Non-interactive mode for automation:**
+
+```bash
+jmotools wizard --yes              # Use smart defaults
+jmotools wizard --docker           # Force Docker mode
+```
+
+**Generate reusable artifacts:**
+
+```bash
+jmotools wizard --emit-make-target Makefile.security  # Team Makefile
+jmotools wizard --emit-script scan.sh                 # Shell script
+jmotools wizard --emit-gha .github/workflows/security.yml  # GitHub Actions
+```
+
+📖 **Full wizard guide:** [docs/examples/wizard-examples.md](docs/examples/wizard-examples.md)
 
-If you're just getting started, use the beginner-friendly wrapper:
+---
 
-- `jmotools fast` — quick scan (fast profile)
-- `jmotools balanced` — default balanced scan
-- `jmotools full` — deep scan with more tools
+### Option 2: 🐳 Docker (Zero Installation)
 
-Examples:
+**Want to start scanning immediately with no tool installation?**
 
 ```bash
-# Fast profile over repos listed in a TSV (auto-clone) and open dashboard when done
-jmotools fast --tsv ai-search/candidates.tsv --dest ./repos-tsv
+# Pull the image (one-time, ~500MB)
+docker pull ghcr.io/jimmy058910/jmo-security:latest
+
+# Scan current directory
+docker run --rm -v $(pwd):/scan ghcr.io/jimmy058910/jmo-security:latest \
+  scan --repo /scan --results /scan/results --profile balanced --human-logs
 
-# Full (deep) profile targeting an existing directory of repos
-jmotools full --repos-dir ./repos-tsv --allow-missing-tools
+# View results
+open results/summaries/dashboard.html  # macOS
+xdg-open results/summaries/dashboard.html  # Linux
 ```
 
-Under the hood, these commands verify your OS/tools, optionally clone from a TSV, run `jmo ci` with the appropriate profile, and open `dashboard.html` and `SUMMARY.md` on completion.
+**Three image variants available:**
+
+- `latest` (~500MB) - All 11+ scanners included
+- `slim` (~200MB) - Core 6 scanners for CI/CD
+- `alpine` (~150MB) - Minimal footprint
+
+📖 **Complete Docker guide:** [docs/DOCKER_README.md](docs/DOCKER_README.md)
+📖 **Beginner Docker tutorial:** [docs/DOCKER_QUICKSTART_BEGINNERS.md](docs/DOCKER_QUICKSTART_BEGINNERS.md)
+
+---
+
+### Option 3: 🧪 CLI Wrapper Commands (Local Install)
+
+**Already have tools installed? Use our simple wrapper commands:**
+
+```bash
+# Quick fast scan (auto-opens results)
+jmotools fast --repos-dir ~/repos
+
+# Balanced scan (recommended default)
+jmotools balanced --repos-dir ~/repos
+
+# Deep scan with all tools
+jmotools full --repos-dir ~/repos
+```
 
-Setup tools quickly:
+**Clone from TSV and scan:**
 
 ```bash
-# Check tools or auto-install on Linux/WSL (where supported)
-jmotools setup --check
-jmotools setup --auto-install         # or --print-commands, --force-reinstall
+jmotools balanced --tsv ./repositories.tsv --dest ./cloned-repos
 ```
 
-Makefile shortcuts:
+**Setup tools quickly:**
 
 ```bash
-make setup             # jmotools setup --check (installs package if needed)
-make fast DIR=~/repos  # jmotools fast --repos-dir ~/repos
+jmotools setup --check              # Verify tool installation
+jmotools setup --auto-install       # Auto-install on Linux/WSL/macOS
+```
+
+**Makefile shortcuts:**
+
+```bash
+make setup             # Verify tools (installs package if needed)
+make fast DIR=~/repos  # Run fast profile
 make balanced DIR=~/repos
 make full DIR=~/repos
 ```
 
+Note: Under the hood, wrapper commands verify your OS/tools, optionally clone from TSV, run `jmo ci` with the appropriate profile, and auto-open results.
+
 ## 🎯 Overview
 
 This project provides an automated framework for conducting thorough security audits on code repositories. It orchestrates multiple industry-standard security tools to detect secrets, vulnerabilities, and security issues.
 
 ### Key Features
 
-- ✅ **Multi-Tool Scanning**: Curated set covering secrets (gitleaks, noseyparker), SAST (semgrep, bandit), SBOM+vuln/misconfig (syft+trivy), IaC (checkov, tfsec), Dockerfile (hadolint)
-- 📊 **Comprehensive Reporting**: Unified findings (JSON/YAML), SARIF, Markdown summary, and an interactive HTML dashboard
-- 🎨 **Easy-to-Read Outputs**: Well-formatted reports with severity categorization
+- ✅ **Multi-Tool Scanning**: Curated set covering secrets (gitleaks, noseyparker, trufflehog), SAST (semgrep, bandit), SBOM+vuln/misconfig (syft+trivy), IaC (checkov, tfsec), Dockerfile (hadolint), and open-source vulnerabilities (osv-scanner)
+- 📊 **Comprehensive Reporting**: Unified findings (JSON/YAML), enriched SARIF 2.1.0 with taxonomies, Markdown summary, and an interactive HTML dashboard with XSS protection
+- 🎨 **Easy-to-Read Outputs**: Well-formatted reports with severity categorization using type-safe enums
 - 🔄 **Automated Workflows**: One CLI to scan, aggregate, and gate on severity (scan/report/ci)
-- 🧭 **Profiles and Overrides**: Named profiles, per-tool flags/timeouts, include/exclude patterns
+- 🧭 **Profiles and Overrides**: Named profiles, per-tool flags/timeouts, include/exclude patterns, configurable thread recommendations
 - 🔁 **Resilience**: Timeouts, retries with per-tool success codes, human-friendly logs, graceful cancel
+- 🔒 **Security-First**: XSS vulnerability patched, comprehensive input escaping, secure-by-default configurations
 
-## 🚀 Quick Start
+## 🚀 Quick Start (Local Installation)
 
 ### Install or Update (curated tools)
 
@@ -125,21 +236,46 @@ Optional: install the package locally to get `jmo` and `jmotools` commands on yo
 pip install -e .
 ```
 
+#### Pre-commit hooks (YAML & Actions validation)
+
+We ship pre-commit hooks for YAML linting and GitHub Actions validation (among other basic checks):
+
+```bash
+make pre-commit-install   # installs the git hooks
+make pre-commit-run       # run checks on all files
+```
+
+These run locally via pre-commit and are also enforced in CI.
+
+We ship a `.yamllint.yaml` and validate GitHub Actions workflows via `actionlint`. The same checks are executed in CI.
+
+#### Reproducible dev dependencies (optional)
+
+This repo ships a `requirements-dev.in` with a compiled `requirements-dev.txt`. Use pip-tools or uv to pin/sync your dev environment:
+
+```bash
+make upgrade-pip
+make deps-compile   # compile dev deps
+make deps-sync      # sync env to compiled lock
+```
+
+CI verifies that `requirements-dev.txt` is up to date on PRs. If it fails, run `make deps-compile` and commit the diff.
+
 ### Quick Start (Unified CLI)
 
-1) Verify your environment (Linux/WSL/macOS) and see install hints for optional tools:
+1. Verify your environment (Linux/WSL/macOS) and see install hints for optional tools:
 
 ```bash
 make verify-env
 ```
 
-2) Install Python dev dependencies (for running tests and reporters):
+1. Install Python dev dependencies (for running tests and reporters):
 
 ```bash
 make dev-deps
 ```
 
-3) Scan repositories using a profile, then aggregate reports:
+1. Scan repositories using a profile, then aggregate reports:
 
 ```bash
 # Scan immediate subfolders under ~/repos with the 'balanced' profile (default)
@@ -150,8 +286,11 @@ python3 scripts/cli/jmo.py scan --repos-dir ~/repos --profile-name balanced --hu
 python3 scripts/cli/jmo.py report ./results --profile --human-logs
 # or
 python3 scripts/cli/jmo.py report --results-dir ./results --profile --human-logs
+```
+
+#### Or do both in one step for CI with a failure threshold
 
-# Or do both in one step for CI with a failure threshold
+```bash
 python3 scripts/cli/jmo.py ci --repos-dir ~/repos --profile-name fast --fail-on HIGH --profile --human-logs
 ```
 
@@ -196,9 +335,9 @@ Prefer the Python CLI above. For legacy flows, you can still use the shell wrapp
 python3 scripts/cli/jmo.py ci --repos-dir ~/test-repos --fail-on HIGH --profile --human-logs
 
 # 3. View results
-cat ~/security-results-*/SUMMARY_REPORT.md
-# macOS: open ~/security-results-*/dashboard.html
-# Linux: xdg-open ~/security-results-*/dashboard.html
+cat results/summaries/SUMMARY.md
+# macOS: open results/summaries/dashboard.html
+# Linux: xdg-open results/summaries/dashboard.html
 ```
 
 Looking for screenshots and how to capture them? See: [docs/screenshots/README.md](docs/screenshots/README.md)
@@ -215,53 +354,44 @@ The security audit follows this workflow:
 4. **Report Generation**: JSON/MD/YAML/HTML/SARIF and suppression summary
 5. **Dashboard Creation**: Self-contained HTML dashboard with an optional profiling panel
 
-### Output Structure
-
-```
-security-results-YYYYMMDD-HHMMSS/
-├── SUMMARY_REPORT.md              # Executive summary
-├── dashboard.html                  # Interactive HTML dashboard
-├── individual-repos/               # Per-repository results
-│   └── [repo-name]/
-│       ├── README.md              # Formatted findings report
-│       ├── gitleaks.json          # Gitleaks raw output
-│       ├── trufflehog.json        # TruffleHog raw output
-│       ├── semgrep.json           # Semgrep raw output
-│       ├── noseyparker.json       # Nosey Parker raw output
-│       └── *.log                  # Tool execution logs
-├── raw-outputs/                   # Compressed per-repo raw artifacts
-├── tool-comparisons/
-│   └── comparison.md              # Tool performance comparison
-├── summaries/
-│   └── metrics.csv                # Aggregated metrics
-
-```
-
-### Report Types
-
-1. **Summary Report** (`SUMMARY_REPORT.md`)
-   - Executive summary
-   - Aggregate statistics
-   - Repository breakdown table
-   - Prioritized recommendations
-
-2. **HTML Dashboard** (`dashboard.html`)
-   - Visual metrics cards
-   - Severity breakdown
-   - Repository comparison table
-   - Tool performance analysis
-
-3. **Individual Reports** (`individual-repos/*/README.md`)
-   - Repository-specific findings
-   - Tool-by-tool breakdown
-   - Detailed issue listings
-   - Severity classifications
-
-4. **Tool Comparison** (`tool-comparisons/comparison.md`)
-   - Detection metrics
-   - Tool capabilities matrix
-   - Implementation strategy guide
-   - Tool selection recommendations
+### Output Structure (Default)
+
+```text
+results/
+├── individual-repos/
+│   └── <repo-name>/
+│       ├── gitleaks.json
+│       ├── trufflehog.json
+│       ├── semgrep.json
+│       ├── noseyparker.json
+│       ├── syft.json
+│       ├── trivy.json
+│       ├── hadolint.json
+│       ├── checkov.json
+│       ├── tfsec.json
+│       └── bandit.json
+└── summaries/
+   ├── findings.json
+   ├── findings.yaml        # requires PyYAML
+   ├── findings.sarif       # SARIF 2.1.0
+   ├── SUMMARY.md
+   ├── dashboard.html
+   ├── SUPPRESSIONS.md      # written when suppressions apply
+   └── timings.json         # written when --profile is used
+```
+
+### Reporters
+
+The aggregator writes unified outputs under `results/summaries/`:
+
+- JSON (`findings.json`) — complete, machine-readable findings list
+- Markdown (`SUMMARY.md`) — human-readable overview with severity counts and top rules
+- YAML (`findings.yaml`) — optional; requires PyYAML
+- HTML (`dashboard.html`) — interactive dashboard with filters, sorting, exports, and theme toggle
+- SARIF (`findings.sarif`) — 2.1.0 for code scanning integrations
+- Suppression summary (`SUPPRESSIONS.md`) — appears when suppression rules filter findings
+
+See `SAMPLE_OUTPUTS.md` for real examples produced from the `infra-demo` fixture.
 
 ### How we normalize findings
 
@@ -271,8 +401,6 @@ All tool outputs are converted into a single CommonFinding schema during aggrega
 - Required fields include: schemaVersion (1.0.0), id, ruleId, severity, tool (name/version), location (path/lines), and message. Optional fields include title, description, remediation, references, tags, cvss, and raw (original tool payload).
 - Fingerprint (id): deterministically derived from a stable subset of attributes (tool | ruleId | path | startLine | message snippet) to support cross-tool dedupe. The aggregation step deduplicates by this id.
 
-
-
 ## 🛠️ Tool Installation
 
 ### macOS (Homebrew)
@@ -319,10 +447,10 @@ curl -sSfL https://raw.githubusercontent.com/trufflesecurity/trufflehog/main/scr
 
 Nosey Parker doesn’t ship via apt/brew universally. Install the release binary and put it on your PATH:
 
-1) Download the latest release for your OS/arch from:
-   https://github.com/praetorian-inc/noseyparker/releases
+1. Download the latest release for your OS/arch from:
+   <https://github.com/praetorian-inc/noseyparker/releases>
 
-2) Unpack and move the binary onto PATH (example for Linux x86_64):
+2. Unpack and move the binary onto PATH (example for Linux x86_64):
 
 ```bash
 tar -xzf noseyparker-*.tar.gz
@@ -339,11 +467,12 @@ On WSL Ubuntu, installing Nosey Parker natively is the most reliable path (prebu
 
 The CLI automatically falls back to a Docker-based Nosey Parker runner when the local binary is missing or not runnable (common on older WSL/glibc). When enabled via profiles, scans will transparently produce the expected JSON here:
 
-```
+```text
 results/individual-repos/<repo-name>/noseyparker.json
 ```
 
 Requirements for the fallback:
+
 - Docker installed and running
 - Ability to pull or use `ghcr.io/praetorian-inc/noseyparker:latest`
 
@@ -380,6 +509,7 @@ Note: we recommend isolating CLI tools via pipx or OS packages for stability. Th
 This helper script streamlines the process of cloning multiple repositories for security scanning, with performance optimizations for WSL environments.
 
 **Features:**
+
 - 🚀 Shallow clones (depth=1) for faster cloning
 - ⚡ Parallel cloning for improved performance
 - 🔄 Unshallow option for secret scanners requiring full history
@@ -405,7 +535,8 @@ This helper script streamlines the process of cloning multiple repositories for
 ```
 
 **Repository List Format (`samples/repos.txt`):**
-```
+
+```text
 # One GitHub repository URL per line
 # Lines starting with # are comments
 https://github.com/user/repo1.git
@@ -413,37 +544,29 @@ https://github.com/user/repo2.git
 ```
 
 **Performance Tips for WSL:**
+
 1. Use shallow clones initially for 10x faster cloning
 2. Adjust `--parallel` based on network speed (default: 4)
 3. Use `--unshallow` only if secret scanners need full git history
 4. Clone to WSL filesystem (not Windows mount) for better performance
 
-### Running Individual Scripts
+### CLI-first usage
 
-1. **Tool Check Only**:
-```bash
-./scripts/core/check_tools.sh
-```
+Prefer the Python CLI for report generation from existing results:
 
-2. **Main Audit Script**:
 ```bash
-./scripts/core/run_security_audit.sh [testing_directory] [output_directory]
-```
+# Default reporters (formats controlled by jmo.yml)
+python3 scripts/cli/jmo.py report /path/to/results
 
-3. **Generate Dashboard Only**:
-```bash
-# Generate dashboard with default output (results_dir/dashboard.html)
-python3 scripts/core/generate_dashboard.py /path/to/results
+# Set thread workers explicitly for aggregation
+python3 scripts/cli/jmo.py report /path/to/results --threads 6
 
-# Generate dashboard with custom output path
-python3 scripts/core/generate_dashboard.py /path/to/results /custom/path/dashboard.html
-```
+# Record profiling timings (writes summaries/timings.json)
+python3 scripts/cli/jmo.py report /path/to/results --profile
 
-The dashboard generator supports:
-- Multiple TruffleHog output formats (JSON arrays, NDJSON, single objects, empty files)
-- Automatic parent directory creation for custom output paths
-- Graceful handling of missing or empty scan results
-- UTF-8 safe file I/O for international characters
+# Human-friendly colored logs (stderr)
+python3 scripts/cli/jmo.py report /path/to/results --human-logs
+```
 
 ### Unified CLI: report-only
 
@@ -486,7 +609,7 @@ python3 scripts/cli/jmo.py ci --repos-dir ~/repos --profile-name balanced --fail
 
 The `summaries/` folder also contains unified outputs:
 
-```
+```text
 summaries/
 ├── findings.json     # Unified normalized findings (machine-readable)
 ├── SUMMARY.md        # Human-readable summary
@@ -503,7 +626,7 @@ You can define named profiles in `jmo.yml` to control which tools run, include/e
 
 Example `jmo.yml` snippet:
 
-```
+```yaml
 default_profile: fast
 retries: 1
 profiles:
@@ -530,7 +653,7 @@ per_tool:
 
 Using a profile from CLI:
 
-```
+```bash
 # Scan using profile 'fast' with human-friendly logs
 python3 scripts/cli/jmo.py scan --repos-dir ~/repos --profile-name fast --human-logs
 
@@ -539,16 +662,12 @@ python3 scripts/cli/jmo.py ci --repos-dir ~/repos --profile-name deep --fail-on
 ```
 
 Retries behavior:
+
 - Global `retries` (or per-profile) retries failed tool commands a limited number of times
 - Some tools use non-zero exit to indicate “findings”; we treat those as success codes to avoid useless retries
 
 Human logs show per-tool retry attempts when > 1, e.g.: `attempts={'semgrep': 2}`
 
-4. **Generate Comparison Report**:
-```bash
-./scripts/core/generate_comparison_report.sh /path/to/results
-```
-
 ### Customizing Tool Execution
 
 Prefer jmo.yml profiles and per_tool overrides. For one-off local tweaks, use:
@@ -567,10 +686,13 @@ python3 scripts/cli/jmo.py scan --repos-dir ~/repos --tools gitleaks semgrep --t
 
 ### Severity Levels
 
+The toolkit uses a type-safe severity enum with comparison operators for consistent filtering and sorting:
+
 - **CRITICAL**: Verified secrets requiring immediate action
 - **HIGH**: Likely secrets or serious vulnerabilities
 - **MEDIUM**: Potential issues requiring review
-- **LOW/INFO**: Informational findings
+- **LOW**: Minor issues for regular maintenance
+- **INFO**: Informational findings
 
 ### Key Metrics
 
@@ -589,46 +711,26 @@ python3 scripts/cli/jmo.py scan --repos-dir ~/repos --tools gitleaks semgrep --t
 ## 🎯 Three-Stage Implementation Strategy
 
 ### Stage 1: Pre-commit Hooks
+
 - **Tool**: Gitleaks
 - **Purpose**: Prevent secrets before commit
 - **Speed**: Fast (suitable for developer workflow)
 
 ### Stage 2: CI/CD Pipeline
+
 - **Tools**: Gitleaks + Semgrep
 - **Purpose**: Automated PR/commit scanning
 - **Coverage**: Secrets + vulnerabilities
 
 ### Stage 3: Deep Periodic Audits
+
 - **Tools**: All tools
 - **Purpose**: Comprehensive security assessment
 - **Frequency**: Weekly/monthly
 
-## 📊 Sample Output
-
-### Dashboard Preview
-The HTML dashboard provides:
-- Visual metric cards with key statistics
-- Severity breakdown tables
-- Repository-by-repository comparison
-- Tool performance analysis
-- Actionable recommendations
-
-### Sample Summary Report
-```markdown
-## Aggregate Results
+## 📊 Sample Outputs
 
-### Overall Statistics
-- Total Issues Found: 1562
-- Critical Issues: 5
-- High Severity Issues: 579
-- Medium Severity Issues: 61
-- Verified Secrets: 5
-
-### Recommendations
-- Rotate all 5 verified secrets immediately
-- Prioritize remediation of 584 critical and high severity issues
-- Schedule follow-up review for the remaining medium findings
-```
+For a current snapshot produced from the `infra-demo` fixture, see: [SAMPLE_OUTPUTS.md](SAMPLE_OUTPUTS.md).
 
 ## 🤝 Contributing
 
@@ -638,7 +740,7 @@ Contributions are welcome! Please feel free to submit pull requests or open issu
 
 If this toolkit saves you time, consider fueling development with an energy drink.
 
-- Prefer one-time tips? Ko‑fi: https://ko-fi.com/jmogaming
+- Prefer one-time tips? Ko‑fi: <https://ko-fi.com/jmogaming>
 - When you’re ready, replace the badge target with your preferred platform: GitHub Sponsors (industry standard), Open Collective, Ko-fi, or Stripe Checkout.
 - GitHub Sponsors integrates directly with your GitHub profile and repository sidebar once enabled.
 
@@ -651,9 +753,6 @@ MIT License. See LICENSE.
 - [Gitleaks Documentation](https://github.com/zricethezav/gitleaks)
 - [TruffleHog Documentation](https://github.com/trufflesecurity/trufflehog)
 - [Semgrep Documentation](https://semgrep.dev)
-- [Nosey Parker Documentation](https://github.com/praetorian-inc/noseyparker)
-
-## 💡 Tips
 
 1. **Start Small**: Test on a single repository first
 2. **Review Regularly**: Schedule periodic audits
@@ -666,22 +765,36 @@ MIT License. See LICENSE.
 ### Common Issues
 
 **Problem**: Tools not found
-- **Solution**: Run `./scripts/cli/security_audit.sh --check` to verify installation
+
+- **Solution**: Run `make verify-env` (or `jmotools setup --check`) to verify installation and get platform-specific hints
 
 **Problem**: JSON parsing errors
+
 - **Solution**: Ensure jq is installed and tools are outputting valid JSON
 
 **Problem**: Permission denied
-- **Solution**: Run `chmod +x *.sh` to make scripts executable
+
+- **Solution**: Ensure scripts are executable:
+
+```bash
+find scripts -type f -name "*.sh" -exec chmod +x {} +
+```
 
 **Problem**: Out of memory
+
 - **Solution**: Scan repositories in smaller batches
 
+```bash
+./scripts/core/populate_targets.sh --unshallow
+```
+
 **Problem**: Path errors (e.g., "//run_security_audit.sh not found")
+
 - **Solution**: This issue has been fixed in the latest version. Update to the latest main branch.
 - The wrapper scripts now use absolute paths computed from the script's real path location.
 
 **Problem**: AttributeError when generating dashboard with TruffleHog results
+
 - **Solution**: This has been fixed. The dashboard generator now handles all TruffleHog output formats:
   - JSON arrays: `[{...}, {...}]`
   - Single objects: `{...}`
@@ -705,11 +818,12 @@ python3 scripts/core/generate_dashboard.py ~/security-results-20251010-120000 ~/
 ```
 
 This is useful when you want to:
+
 - Update the dashboard after manually editing JSON files
 - Generate multiple dashboards with different configurations
 - Share results by exporting to a specific location
 
 ---
 
-**Last Updated**: October 10th, 2025
+**Last Updated**: October 13th, 2025
 **Author**: James Moceri