diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 8fdf255..f6cf749 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -23,11 +23,11 @@ jobs: build: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v4 + - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1 - - uses: astral-sh/setup-uv@v4 + - uses: astral-sh/setup-uv@cec208311dfd045dd5311c1add060b2062131d57 # v8.0.0 - - uses: actions/setup-python@v5 + - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0 with: python-version: '3.12' @@ -46,7 +46,7 @@ jobs: CI: true - name: Upload artifact - uses: actions/upload-pages-artifact@v3 + uses: actions/upload-pages-artifact@56afc609e74202658d3ffba0e8f6dda462b719fa # v3.0.1 with: path: docs-site/site @@ -59,4 +59,4 @@ jobs: steps: - name: Deploy to GitHub Pages id: deployment - uses: actions/deploy-pages@v4 + uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e # v4.0.5 diff --git a/Makefile b/Makefile index 39c8638..1dae625 100644 --- a/Makefile +++ b/Makefile @@ -815,25 +815,27 @@ fuzz: # ============= DOCUMENTATION ============= +DOCS_REQUIREMENTS := docs-site/requirements.txt + docs-build: @echo "📝 Preparing documentation…" - @uv run --with mkdocs-material --with mkdocs-minify-plugin --with pyyaml \ + @uv run --with-requirements $(DOCS_REQUIREMENTS) \ python3 docs-site/scripts/prepare-docs.py - @uv run --with mkdocs-material --with mkdocs-minify-plugin --with pyyaml \ + @uv run --with-requirements $(DOCS_REQUIREMENTS) \ python3 docs-site/scripts/generate-rules-page.py @echo "🔨 Building site…" - @cd docs-site && uv run --with mkdocs-material --with mkdocs-minify-plugin \ + @cd docs-site && uv run --with-requirements requirements.txt \ mkdocs build @echo "✅ Site built at docs-site/site/" docs-serve: @echo "📝 Preparing documentation…" - @uv run --with mkdocs-material --with mkdocs-minify-plugin --with pyyaml \ + @uv run --with-requirements $(DOCS_REQUIREMENTS) \ python3 docs-site/scripts/prepare-docs.py - @uv run --with mkdocs-material --with mkdocs-minify-plugin --with pyyaml \ + @uv run --with-requirements $(DOCS_REQUIREMENTS) \ python3 docs-site/scripts/generate-rules-page.py @echo "🌐 Starting dev server at http://127.0.0.1:8000/" - @cd docs-site && uv run --with mkdocs-material --with mkdocs-minify-plugin \ + @cd docs-site && uv run --with-requirements requirements.txt \ mkdocs serve docs-clean: diff --git a/docs-site/docs/features/agents.md b/docs-site/docs/features/agents.md index ff75282..43e98f2 100644 --- a/docs-site/docs/features/agents.md +++ b/docs-site/docs/features/agents.md @@ -84,15 +84,18 @@ kingfisher scan . --since-commit origin/main --format json For deep integration, use Kingfisher as a library in your Rust-based agent: ```rust -use kingfisher_scanner::ScannerBuilder; -use kingfisher_rules::RuleDatabase; +use std::sync::Arc; +use kingfisher_rules::defaults::get_builtin_rules; +use kingfisher_rules::RulesDatabase; +use kingfisher_scanner::Scanner; -// Build a scanner with default rules -let rules = RuleDatabase::from_default_rules()?; -let scanner = ScannerBuilder::new(&rules).build()?; +// Load the built-in rules and compile the scanner database +let rules = get_builtin_rules(None)?; +let rules_db = Arc::new(RulesDatabase::from_rules(rules.into_rules())?); +let mut scanner = Scanner::new(rules_db); -// Scan a string -let findings = scanner.scan_blob("my text with secrets")?; +// Scan a byte slice for secrets +let findings = scanner.scan_bytes(b"AKIA..."); ``` See [Rust Library Crates](../reference/library.md) for complete documentation. diff --git a/docs-site/docs/reference/library.md b/docs-site/docs/reference/library.md index 4aa7faf..8b4d871 100644 --- a/docs-site/docs/reference/library.md +++ b/docs-site/docs/reference/library.md @@ -868,6 +868,6 @@ These crates are currently internal to Kingfisher. The API may change between ve ## See Also -- [Main README](../README.md) - CLI usage and installation +- [Main README](../getting-started/quick-start.md) - CLI usage and installation - [Rule Format](../features/fingerprints.md) - Rule definition details -- [Changelog](../CHANGELOG.md) - Version history +- [Changelog](../changelog.md) - Version history diff --git a/docs-site/scripts/generate-rules-page.py b/docs-site/scripts/generate-rules-page.py index 406343a..00debbf 100644 --- a/docs-site/scripts/generate-rules-page.py +++ b/docs-site/scripts/generate-rules-page.py @@ -4,10 +4,11 @@ Reads all YAML rule definition files from crates/kingfisher-rules/data/rules/ and generates a searchable markdown page listing all built-in rules. """ -import os -import yaml +from html import escape from pathlib import Path +import yaml + REPO_ROOT = Path(__file__).resolve().parent.parent.parent RULES_DIR = REPO_ROOT / "crates" / "kingfisher-rules" / "data" / "rules" OUTPUT = REPO_ROOT / "docs-site" / "docs" / "rules" / "builtin-rules.md" @@ -107,15 +108,18 @@ def generate_markdown(rules): for rule in sorted(rules, key=lambda r: (r["provider"].lower(), r["id"])): validates = "Yes" if rule["validates"] else "" revokes = "Yes" if rule["revokes"] else "" - confidence = rule["confidence"].capitalize() - lines.append(f'') - lines.append(f'{rule["provider"]}') - lines.append(f'{rule["name"]}') - lines.append(f'{rule["id"]}') + confidence = escape(rule["confidence"].capitalize()) + provider = escape(rule["provider"]) + name = escape(rule["name"]) + rule_id = escape(rule["id"]) + lines.append('') + lines.append(f'{provider}') + lines.append(f'{name}') + lines.append(f'{rule_id}') lines.append(f'{confidence}') lines.append(f'{validates}') lines.append(f'{revokes}') - lines.append(f'') + lines.append('') lines.extend([ '', diff --git a/docs-site/scripts/prepare-docs.py b/docs-site/scripts/prepare-docs.py index 15ab278..6f8226c 100644 --- a/docs-site/scripts/prepare-docs.py +++ b/docs-site/scripts/prepare-docs.py @@ -8,7 +8,6 @@ Copies documentation from /docs/ into docs-site/docs/ with transformations: import os import re -import shutil REPO_ROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), "..", "..")) DOCS_SRC = os.path.join(REPO_ROOT, "docs") @@ -156,6 +155,10 @@ def rewrite_links(content: str) -> str: content = content.replace("](./runtime-comparison.png", "](../assets/images/runtime-comparison.png") content = content.replace('src="./runtime-comparison.png"', 'src="../assets/images/runtime-comparison.png"') content = content.replace("](./assets/icons/", "](../assets/icons/") + + # Rewrite links to files that live at non-standard site locations + content = content.replace("](../README.md)", "](../getting-started/quick-start.md)") + content = content.replace("](../CHANGELOG.md)", "](../changelog.md)") return content