Skip to content

GitHub Pages

Overview

GitHub Pages hosts BAB documentation, security reports, and test coverage information at https://gicsei.github.io/BAB/.

Content Structure

Documentation (/)

Full MkDocs Material site containing: - API reference - Architecture guide - Setup instructions (Windows, Linux, Docker, TrueNAS) - Deployment guide - Security notes - Testing guide - CI/CD pipeline documentation - Troubleshooting

Updated on: Every push to main and on version tag push.

Security Reports (/reports/security/)

HTML security scan reports generated from CI/CD scans.

Structure

/reports/security/
├── latest/               ← Symlink to most recent release
│   ├── trivy.html        ← OS/library CVE scan
│   ├── bandit.html       ← Code security analysis
│   └── pip-audit.html    ← Dependency vulnerability scan
└── v1.2.3/              ← Per-release reports
    ├── trivy.html
    ├── bandit.html
    └── pip-audit.html

Report Details

Trivy Report (trivy.html): OS and library vulnerability scan of the production Docker image. Lists all CVEs found with severity levels (LOW, MEDIUM, HIGH, CRITICAL).

Bandit Report (bandit.html): Static analysis of Python code for security anti-patterns (hardcoded secrets, SQL injection, unsafe deserialization, etc.). Organized by severity and file location.

Pip-Audit Report (pip-audit.html): Python dependency vulnerability scan. Lists all packages with known CVEs and available fixes.

Metadata: Each report includes timestamp, tool version, and summary counts by severity.

Report Generation

Reports are generated by scripts/generate-security-reports.py:

# Convert JSON scan results to HTML
python scripts/generate-security-reports.py \
  --trivy-json reports/trivy-release.json \
  --bandit-json reports/bandit-release.json \
  --pip-audit-json reports/pip-audit-release.json \
  --output reports/security/v1.2.3/

Inputs: JSON output from Trivy, bandit, and pip-audit CLI tools.

Output: HTML reports rendered with summary tables and issue details.

Template: Jinja2 template in the script provides consistent styling and formatting across all reports.

Update Frequency

  • On release tag push: Full security reports published for the version (e.g. vX.Y.Z/).
  • On main branch push: Reports updated in latest/ directory.

Coverage Reports (/reports/coverage/)

Test coverage HTML reports (if configured in CI).

Trigger: Generated by pytest --cov and uploaded on main branch push or release.

Test Reports (/reports/test-reports/)

Pytest HTML test results (if configured in CI).

Trigger: Generated by pytest and uploaded on main branch push or release.

Deployment Process

GitHub Pages deployment is handled by pages.yml workflow:

  1. Trigger: Push to main, release tag (v*), or manual dispatch.
  2. Build: Installs MkDocs Material and runs mkdocs build --strict.
  3. Artifacts: Collects security reports from previous CI runs.
  4. Deploy: Uploads built site + reports as Pages artifact.
  5. Concurrency: Only one deployment at a time; in-flight runs are not cancelled.

Viewing Reports

Via GitHub Pages

  • Docs: https://gicsei.github.io/BAB/
  • Latest Security: https://gicsei.github.io/BAB/reports/security/latest/
  • Release vX.Y.Z: https://gicsei.github.io/BAB/reports/security/vX.Y.Z/

Via GitHub Actions Artifacts

Security reports are also available as CI artifacts during development:

  1. Go to the failed CI run in Actions.
  2. Download artifact: security-scan-validate or security-scan-release.
  3. Extract and open HTML reports locally.

Customizing Pages Content

Update Documentation

Edit .md files in docs/ directory. MkDocs Material will automatically render them.

Configuration: mkdocs.yml defines site structure, navigation, and theme.

Strict mode: mkdocs build --strict enforces no broken links or syntax errors. Test locally:

uv run mkdocs build --strict

Update Report Templates

Edit scripts/generate-security-reports.py:

  • REPORT_TEMPLATE: Jinja2 HTML template for rendering scan results.
  • CSS styling: Update <style> section for colors, layout, and responsive design.
  • Report sections: Add or remove fields from the summary and details tables.

After changes, rebuild reports locally:

python scripts/generate-security-reports.py --help

Troubleshooting

Pages not updating: Check the pages.yml workflow run in Actions. Ensure .github/workflows/pages.yml is not disabled and deployment is set to "GitHub Actions" in Settings → Pages.

Report links broken: Verify report directory structure matches URLs in documentation. Check that generate-security-reports.py is uploading to the correct paths in CI.

MkDocs build fails: Run mkdocs build --strict locally to catch syntax errors. Common issues: broken links, missing navigation entries, or invalid YAML in mkdocs.yml.

  • CI/CD Pipeline — How workflows generate reports and security scans.
  • Security — Details on each scanning tool (pip-audit, bandit, Trivy).
  • Deployment — Release process and manual deployment steps.