@teevee98/synapse-hub 0.0.0-stage → 3.8.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.agents/agents/api-engineer.md +67 -0
- package/.agents/agents/failure-analyst.md +75 -0
- package/.agents/agents/live-explorer.md +70 -0
- package/.agents/agents/orchestrator.md +104 -0
- package/.agents/agents/perf-engineer.md +74 -0
- package/.agents/agents/pom-crafter.md +112 -0
- package/.agents/agents/quality-gatekeeper.md +87 -0
- package/.agents/agents/test-designer.md +73 -0
- package/.agents/agents/test-runner.md +67 -0
- package/.agents/rules/author-integrity-guard.md +33 -0
- package/.agents/rules/communication-style.md +18 -0
- package/.agents/rules/context-engineering.md +37 -0
- package/.agents/rules/git-push-protocol.md +33 -0
- package/.agents/rules/graphify.md +14 -0
- package/.agents/rules/lessons-learned.md +25 -0
- package/.agents/rules/mandatory-playwright-live.md +25 -0
- package/.agents/rules/mobile_appium_rules.md +43 -0
- package/.agents/rules/performance_testing_rules.md +35 -0
- package/.agents/rules/skill-precedence.md +29 -0
- package/.agents/rules/systematic-debugging.md +36 -0
- package/.agents/skills/actor-qa-swarm/SKILL.md +77 -0
- package/.agents/skills/actor-qa-swarm/examples/broker_sharding_sample.json +12 -0
- package/.agents/skills/agent-orchestration-multi-agent-optimize/SKILL.md +88 -0
- package/.agents/skills/agent-orchestration-multi-agent-optimize/examples/swarm_workload_config.json +15 -0
- package/.agents/skills/agentless-qa-repair/SKILL.md +69 -0
- package/.agents/skills/agentless-qa-repair/examples/healing_report_sample.json +17 -0
- package/.agents/skills/agentless-qa-repair/examples/three_phase_repair_workflow.md +40 -0
- package/.agents/skills/antigravity-test-sentinel/SKILL.md +63 -0
- package/.agents/skills/antigravity-test-sentinel/examples/dod_gate_policy.json +11 -0
- package/.agents/skills/antigravity-test-sentinel/examples/sprint_dod_enforcement.md +47 -0
- package/.agents/skills/api-network-mocking-interception/SKILL.md +142 -0
- package/.agents/skills/api-network-mocking-interception/examples/network_route_stub.json +9 -0
- package/.agents/skills/api-spec-to-e2e-matrix/SKILL.md +80 -0
- package/.agents/skills/api-spec-to-e2e-matrix/examples/sample_openapi.json +19 -0
- package/.agents/skills/architecture-decision-records/SKILL.md +64 -0
- package/.agents/skills/architecture-decision-records/examples/0001-record-architecture-decisions.md +12 -0
- package/.agents/skills/auth-session-and-cookie-manager/SKILL.md +75 -0
- package/.agents/skills/auth-session-and-cookie-manager/examples/multi_role_auth_matrix.md +70 -0
- package/.agents/skills/auth-session-and-cookie-manager/examples/storage_state_sample.json +11 -0
- package/.agents/skills/backend-load-and-stress-patterns/SKILL.md +85 -0
- package/.agents/skills/backend-load-and-stress-patterns/examples/k6_load_test_sample.js +13 -0
- package/.agents/skills/backend-load-and-stress-patterns/references/k6_load_template.js +82 -0
- package/.agents/skills/bats-testing-patterns/SKILL.md +100 -0
- package/.agents/skills/bats-testing-patterns/examples/cli_runner_test.bats +6 -0
- package/.agents/skills/bats-testing-patterns/resources/implementation-playbook.md +614 -0
- package/.agents/skills/clean-pom-crafter/SKILL.md +110 -0
- package/.agents/skills/clean-pom-crafter/examples/standard_test_case.groovy +28 -0
- package/.agents/skills/clean-pom-crafter/references/pom_patterns.groovy +138 -0
- package/.agents/skills/code-refactoring-refactor-clean/SKILL.md +64 -0
- package/.agents/skills/code-refactoring-refactor-clean/examples/refactored_page_sample.groovy +9 -0
- package/.agents/skills/code-refactoring-refactor-clean/examples/refactored_playwright_pom.ts +52 -0
- package/.agents/skills/code-refactoring-refactor-clean/resources/implementation-playbook.md +881 -0
- package/.agents/skills/consumer-driven-contract-testing/SKILL.md +147 -0
- package/.agents/skills/consumer-driven-contract-testing/examples/order_service_pact.json +45 -0
- package/.agents/skills/db-state-verifier-and-seeder/SKILL.md +123 -0
- package/.agents/skills/db-state-verifier-and-seeder/examples/db_fixture_seed.json +12 -0
- package/.agents/skills/e2e-testing-patterns/SKILL.md +103 -0
- package/.agents/skills/e2e-testing-patterns/examples/playwright_sharded_config.ts +12 -0
- package/.agents/skills/e2e-testing-patterns/resources/implementation-playbook.md +522 -0
- package/.agents/skills/event-stream-qa-orchestrator/SKILL.md +79 -0
- package/.agents/skills/event-stream-qa-orchestrator/examples/timeline_sample.jsonl +2 -0
- package/.agents/skills/failure-autopsy-and-healing/SKILL.md +66 -0
- package/.agents/skills/failure-autopsy-and-healing/examples/closed_loop_healing_walkthrough.md +48 -0
- package/.agents/skills/failure-autopsy-and-healing/examples/sample_junit_failure.xml +8 -0
- package/.agents/skills/failure-autopsy-and-healing/references/healing_matrix.md +64 -0
- package/.agents/skills/failure-autopsy-and-healing/references/qa_investigation_protocol.md +56 -0
- package/.agents/skills/failure-autopsy-and-healing/scripts/triage_failures.sh +83 -0
- package/.agents/skills/file-and-report-validator/SKILL.md +90 -0
- package/.agents/skills/file-and-report-validator/examples/sample_export_schema.json +14 -0
- package/.agents/skills/flaky-test-sentinel-and-quarantine/SKILL.md +114 -0
- package/.agents/skills/flaky-test-sentinel-and-quarantine/examples/quarantine_registry.json +11 -0
- package/.agents/skills/gherkin-to-suite/SKILL.md +103 -0
- package/.agents/skills/gherkin-to-suite/examples/checkout.feature +39 -0
- package/.agents/skills/gherkin-to-suite/examples/suite_report_sample.json +334 -0
- package/.agents/skills/github-actions-templates/SKILL.md +77 -0
- package/.agents/skills/github-actions-templates/examples/matrix_test_pipeline.yml +8 -0
- package/.agents/skills/graphify-impact-analyzer/SKILL.md +76 -0
- package/.agents/skills/graphify-impact-analyzer/examples/dependency_blast_radius.json +8 -0
- package/.agents/skills/katalon-cli-runner/SKILL.md +76 -0
- package/.agents/skills/katalon-cli-runner/examples/headless_kre_exec.sh +3 -0
- package/.agents/skills/katalon-cli-runner/references/groovy-patterns.md +209 -0
- package/.agents/skills/katalon-cli-runner/references/katalon-api.md +155 -0
- package/.agents/skills/katalon-cli-runner/references/runner_commands.md +67 -0
- package/.agents/skills/lam-script-generator/SKILL.md +123 -0
- package/.agents/skills/lam-script-generator/examples/user_story_sample.md +8 -0
- package/.agents/skills/lean-code-ladder/SKILL.md +94 -0
- package/.agents/skills/lean-code-ladder/examples/ladder_walkthrough.md +37 -0
- package/.agents/skills/lean-impact-scoreboard/SKILL.md +48 -0
- package/.agents/skills/lean-impact-scoreboard/examples/sample_benchmark_gain.md +20 -0
- package/.agents/skills/lean-impact-scoreboard/examples/sample_scoreboard.md +15 -0
- package/.agents/skills/meta-prompt-crafter/SKILL.md +107 -0
- package/.agents/skills/meta-prompt-crafter/examples/qa_prompt_template.md +35 -0
- package/.agents/skills/mipro-prompt-compiler/SKILL.md +59 -0
- package/.agents/skills/mipro-prompt-compiler/examples/compiled_module_sample.json +22 -0
- package/.agents/skills/mipro-prompt-compiler/examples/dspy_assertion_optimizer_case.md +46 -0
- package/.agents/skills/mobile-appium-som/SKILL.md +88 -0
- package/.agents/skills/mobile-appium-som/examples/BaseScreen.java +88 -0
- package/.agents/skills/mobile-appium-som/examples/LoginScreen.java +46 -0
- package/.agents/skills/mobile-appium-som/examples/TC_MobileLogin.java +43 -0
- package/.agents/skills/persistent-planning-files/SKILL.md +108 -0
- package/.agents/skills/persistent-planning-files/examples/task_plan_example.md +56 -0
- package/.agents/skills/playwright-live-interaction/SKILL.md +131 -0
- package/.agents/skills/playwright-live-interaction/examples/live_probe_script.js +5 -0
- package/.agents/skills/playwright-live-interaction/references/advanced_superpowers.md +160 -0
- package/.agents/skills/playwright-live-interaction/references/compact_accessibility_snapshots.md +75 -0
- package/.agents/skills/playwright-live-interaction/references/recipes.md +388 -0
- package/.agents/skills/playwright-live-interaction/references/swarm_orchestration.md +134 -0
- package/.agents/skills/playwright-webapp-testing/SKILL.md +93 -0
- package/.agents/skills/playwright-webapp-testing/examples/server_lifecycle_playwright.py +63 -0
- package/.agents/skills/qa-aci-interface/SKILL.md +67 -0
- package/.agents/skills/qa-aci-interface/examples/surgical_code_window_walkthrough.md +40 -0
- package/.agents/skills/qa-aci-interface/examples/surgical_edit_sample.json +12 -0
- package/.agents/skills/qa-memory-os/SKILL.md +80 -0
- package/.agents/skills/qa-memory-os/examples/archival_memory_sample.json +21 -0
- package/.agents/skills/rbt-manual-testing/SKILL.md +137 -0
- package/.agents/skills/rbt-manual-testing/examples/checkout_rbt_manual_suite.md +25 -0
- package/.agents/skills/rbt-manual-testing/references/field_validation_checklist.md +29 -0
- package/.agents/skills/repo-quality-audit/SKILL.md +68 -0
- package/.agents/skills/repo-quality-audit/examples/sample_audit_walkthrough.md +15 -0
- package/.agents/skills/repo-quality-audit/examples/sample_repo_audit.md +33 -0
- package/.agents/skills/review-spec/SKILL.md +60 -0
- package/.agents/skills/review-spec/examples/pocock_grilling_decision_rubric.md +40 -0
- package/.agents/skills/review-spec/examples/sample_spec_review.md +33 -0
- package/.agents/skills/security-dast-sentinel/SKILL.md +119 -0
- package/.agents/skills/security-dast-sentinel/examples/dast_scan_config.json +10 -0
- package/.agents/skills/security-dast-sentinel/references/AI-AND-LLM.md +113 -0
- package/.agents/skills/security-dast-sentinel/references/ATTACK-CLASSES.md +89 -0
- package/.agents/skills/security-dast-sentinel/references/dast_recipes.ts +33 -0
- package/.agents/skills/self-healing-locator/SKILL.md +86 -0
- package/.agents/skills/self-healing-locator/examples/aom_diff_sample.json +16 -0
- package/.agents/skills/senior-code-review/SKILL.md +108 -0
- package/.agents/skills/senior-code-review/examples/sample_review_walkthrough.md +29 -0
- package/.agents/skills/skillspector-security-guard/SKILL.md +57 -0
- package/.agents/skills/skillspector-security-guard/examples/audit_threat_vectors_report.json +35 -0
- package/.agents/skills/skillspector-security-guard/examples/safe_mcp_config.json +12 -0
- package/.agents/skills/surgical-coding-principles/SKILL.md +89 -0
- package/.agents/skills/surgical-coding-principles/examples/surgical_vs_scope_creep.md +46 -0
- package/.agents/skills/synthetic-test-data-generator/SKILL.md +135 -0
- package/.agents/skills/synthetic-test-data-generator/examples/idempotent_data_recipe.json +9 -0
- package/.agents/skills/systematic-debugging/SKILL.md +100 -0
- package/.agents/skills/systematic-debugging/examples/four_phase_case.md +44 -0
- package/.agents/skills/technical-debt-harvester/SKILL.md +70 -0
- package/.agents/skills/technical-debt-harvester/examples/sample_debt_ledger.md +25 -0
- package/.agents/skills/technical-debt-harvester/examples/sample_ledger_output.md +20 -0
- package/.agents/skills/test-driven-development/SKILL.md +114 -0
- package/.agents/skills/test-driven-development/examples/red_green_refactor_qa.md +78 -0
- package/.agents/skills/token-and-context-optimizer/SKILL.md +70 -0
- package/.agents/skills/token-and-context-optimizer/examples/distilled_log_sample.txt +3 -0
- package/.agents/skills/token-and-context-optimizer/references/context_engineering_guide.md +49 -0
- package/.agents/skills/tot-exploratory-testing/SKILL.md +59 -0
- package/.agents/skills/tot-exploratory-testing/examples/payment_gateway_tot_tree.json +62 -0
- package/.agents/skills/tot-exploratory-testing/examples/tot_graph_sample.json +35 -0
- package/.agents/skills/verification-before-completion/SKILL.md +100 -0
- package/.agents/skills/verification-before-completion/examples/evidence_log_example.md +46 -0
- package/.agents/skills/visual-regression-sentinel/SKILL.md +82 -0
- package/.agents/skills/visual-regression-sentinel/examples/visual_mask_rules.json +9 -0
- package/.agents/skills/wcag-audit-patterns/SKILL.md +77 -0
- package/.agents/skills/wcag-audit-patterns/examples/wcag_compliance_checklist.json +10 -0
- package/.agents/skills/wcag-audit-patterns/resources/implementation-playbook.md +541 -0
- package/.agents/skills/web-agent-gym-benchmarking/SKILL.md +62 -0
- package/.agents/skills/web-agent-gym-benchmarking/examples/benchmark_report_sample.json +22 -0
- package/.agents/skills/web-agent-gym-benchmarking/examples/enterprise_tasks_suite.json +38 -0
- package/.agents/skills/web-vitals-and-performance-profiler/SKILL.md +65 -0
- package/.agents/skills/web-vitals-and-performance-profiler/examples/cwv_budget_policy.json +6 -0
- package/.agents/skills/web-vitals-and-performance-profiler/examples/playwright_cwv_profiler_fixture.ts +118 -0
- package/.agents/templates/completion_report.md +57 -0
- package/.agents/workflows/analyze_requirement_document.md +18 -0
- package/.agents/workflows/export_testcases_excel.md +32 -0
- package/.agents/workflows/generate_combinatorial_test_data.md +28 -0
- package/.agents/workflows/generate_cross_module_test_plan.md +37 -0
- package/.agents/workflows/generate_manual_testcases_rbt.md +56 -0
- package/.agents/workflows/generate_requirements_from_website.md +25 -0
- package/.agents/workflows/generate_testcases_from_requirements.md +21 -0
- package/.agents/workflows/graphify.md +10 -0
- package/.agents/workflows/test-impact.md +15 -0
- package/.agents/workflows/verify.md +34 -0
- package/.cursor/rules/agents.mdc +16 -0
- package/.cursor/rules/language.mdc +7 -0
- package/.cursor/rules/synapse-qa.mdc +24 -0
- package/.cursorrules +27 -0
- package/.dockerignore +53 -0
- package/.pre-commit-hooks.yaml +14 -0
- package/.windsurfrules +26 -0
- package/AGENTS.md +86 -0
- package/CLAUDE.md +54 -0
- package/Dockerfile +81 -0
- package/LICENSE +52 -0
- package/NOTICE +264 -0
- package/README.en.md +171 -0
- package/README.md +170 -2
- package/action.yml +51 -0
- package/agentskills.json +16 -0
- package/bin/agent-qa.js +138 -0
- package/docker-compose.yml +74 -0
- package/docs/ARCHITECTURE.en.md +198 -0
- package/docs/ARCHITECTURE.md +199 -0
- package/docs/CI_CD_INTEGRATION.en.md +170 -0
- package/docs/CI_CD_INTEGRATION.md +170 -0
- package/docs/CLI_REFERENCE.en.md +174 -0
- package/docs/CLI_REFERENCE.md +176 -0
- package/docs/CONTRIBUTING.en.md +49 -0
- package/docs/CONTRIBUTING.md +49 -0
- package/docs/PERFORMANCE_AUDIT_REPORT.md +783 -0
- package/docs/PLUGIN_DEVELOPMENT_GUIDE.md +127 -0
- package/docs/QUALITY_GATES.en.md +118 -0
- package/docs/QUALITY_GATES.md +118 -0
- package/docs/TOKEN_QUOTA_PLAYBOOK.md +41 -0
- package/docs/TOOL_CATALOG.md +129 -0
- package/docs/adopted-ecosystem-tools.md +96 -0
- package/docs/research/EXTERNAL_AGENT_SKILLS_SURVEY.md +1062 -0
- package/docs/research/agent_skill_training_analysis.md +1358 -0
- package/docs/schemas/synapse.config.schema.json +86 -0
- package/package.json +94 -4
- package/plugin.json +31 -0
- package/scripts/generate_skill_examples.py +244 -0
- package/scripts/install.ps1 +112 -0
- package/scripts/install_global_plugin.ps1 +94 -0
- package/scripts/install_global_plugin.sh +49 -0
- package/scripts/lint_skills.ps1 +57 -0
- package/scripts/package_dist.py +337 -0
- package/scripts/setup.sh +59 -0
- package/scripts/update_hub.ps1 +19 -0
- package/scripts/update_hub.sh +15 -0
- package/skills_manifest.json +854 -0
- package/synapse.config.json +31 -0
- package/templates/PROJECT_AI_GUIDE_TEMPLATE.md +111 -0
- package/templates/PROJECT_STATE_TEMPLATE.md +20 -0
- package/templates/ai_bridges/CLAUDE.md +54 -0
- package/templates/ai_bridges/copilot-instructions.md +20 -0
- package/templates/ai_bridges/cursor_synapse_qa.mdc +24 -0
- package/templates/ai_bridges/windsurfrules +26 -0
- package/templates/ci/github-actions-synapse.yml +95 -0
- package/templates/ci/gitlab-ci-synapse.yml +16 -0
- package/templates/ui/index.html +1069 -0
- package/templates/welcome.html.tmpl +2074 -0
- package/tools/.infer_baseline.json +30 -0
- package/tools/TOOLS_RUNBOOK.md +1553 -0
- package/tools/TOOL_CATALOG.json +1769 -0
- package/tools/__init__.py +43 -0
- package/tools/_openapi_parser.py +158 -0
- package/tools/agent_canary.py +525 -0
- package/tools/agentless_patcher.py +417 -0
- package/tools/analyze_project.py +262 -0
- package/tools/api_drift_sentinel.py +208 -0
- package/tools/api_fuzzer.py +762 -0
- package/tools/author_integrity.py +190 -0
- package/tools/auto_heal.py +271 -0
- package/tools/auto_heal_reflexion.py +532 -0
- package/tools/autogen_qa_broker.py +844 -0
- package/tools/benchmark_swarm_context.py +394 -0
- package/tools/browser_helpers.js +746 -0
- package/tools/browsergym_eval.py +236 -0
- package/tools/bug_reporter.py +252 -0
- package/tools/bump_version.py +423 -0
- package/tools/cache_resolver.py +1214 -0
- package/tools/check_env.py +426 -0
- package/tools/check_version_sync.py +256 -0
- package/tools/ci_healing_hook.py +126 -0
- package/tools/cli.py +1598 -0
- package/tools/config_decoupler.py +253 -0
- package/tools/contract_validator.py +141 -0
- package/tools/core/__init__.py +70 -0
- package/tools/core/adapters.py +431 -0
- package/tools/core/circuit_breaker.py +263 -0
- package/tools/core/cli_runtime.py +66 -0
- package/tools/core/file_lock.py +159 -0
- package/tools/core/i18n.py +394 -0
- package/tools/core/memory_bus.py +905 -0
- package/tools/core/process_supervisor.py +332 -0
- package/tools/core/telemetry.py +329 -0
- package/tools/count_tokens.py +1267 -0
- package/tools/create_mock_docx.py +104 -0
- package/tools/dashboard_generator.py +2403 -0
- package/tools/db_sandbox.py +675 -0
- package/tools/debt_harvester.py +237 -0
- package/tools/distill_log.py +161 -0
- package/tools/dspy_qa_signatures.py +356 -0
- package/tools/e2e_flow_prober.py +132 -0
- package/tools/export_postman_collection.py +945 -0
- package/tools/flaky_detector.py +389 -0
- package/tools/fsm_enforcer.py +450 -0
- package/tools/fsm_middleware.py +401 -0
- package/tools/fuzz_payloads.py +197 -0
- package/tools/generate_allure_report.py +88 -0
- package/tools/generate_api_matrix.py +193 -0
- package/tools/generate_jmx_plan.py +1322 -0
- package/tools/generate_sbom.py +252 -0
- package/tools/generate_tc_from_story.py +203 -0
- package/tools/generate_test_reports.py +133 -0
- package/tools/generate_tool_catalog.py +482 -0
- package/tools/gherkin_suite.py +758 -0
- package/tools/git_pre_commit_guard.py +298 -0
- package/tools/goldfish_review.py +366 -0
- package/tools/heal/__init__.py +28 -0
- package/tools/heal_pr_automator.py +220 -0
- package/tools/heuristic_locator_matcher.py +351 -0
- package/tools/hub_publisher.py +623 -0
- package/tools/humanize_linter.py +438 -0
- package/tools/infer_linter.py +977 -0
- package/tools/init_config.py +306 -0
- package/tools/interview_story.py +116 -0
- package/tools/jira_sync.py +566 -0
- package/tools/jtl_analyzer.py +474 -0
- package/tools/lint/__init__.py +30 -0
- package/tools/lint_ai_docs.py +374 -0
- package/tools/lookup_tc.py +165 -0
- package/tools/lookup_xpath.py +167 -0
- package/tools/matrix_sharder.py +148 -0
- package/tools/mcp/__init__.py +18 -0
- package/tools/mcp_docx_server.ps1 +13 -0
- package/tools/mcp_docx_server.py +851 -0
- package/tools/mcp_excel_server.ps1 +13 -0
- package/tools/mcp_excel_server.py +441 -0
- package/tools/mcp_server.py +725 -0
- package/tools/md_to_xlsx.py +327 -0
- package/tools/micro_mutator.py +887 -0
- package/tools/mipro_assertion_tuner.py +210 -0
- package/tools/network_mock_shield.py +311 -0
- package/tools/newman_analyzer.py +384 -0
- package/tools/omni_emitter.py +579 -0
- package/tools/omni_parser.py +450 -0
- package/tools/omni_transpiler.py +168 -0
- package/tools/openxml_guard.py +438 -0
- package/tools/output_formatter.py +182 -0
- package/tools/package_release.py +325 -0
- package/tools/perf/__init__.py +24 -0
- package/tools/pinpoint_failure.py +190 -0
- package/tools/project_state.py +171 -0
- package/tools/qa_event_stream.py +358 -0
- package/tools/repo_map.py +346 -0
- package/tools/report/__init__.py +32 -0
- package/tools/reversible_sandbox.py +344 -0
- package/tools/safety_firewall.py +437 -0
- package/tools/security_coverage_ledger.py +538 -0
- package/tools/security_scanner.py +229 -0
- package/tools/senior_code_review.py +393 -0
- package/tools/setup_project.py +770 -0
- package/tools/skill_collision_guard.py +304 -0
- package/tools/skill_profiles.py +217 -0
- package/tools/skill_vault.py +481 -0
- package/tools/skillspector.py +1278 -0
- package/tools/smart_visual_masker.py +132 -0
- package/tools/spec_drift_sentinel.py +438 -0
- package/tools/swe_qa_aci.py +369 -0
- package/tools/synapse_observer.py +485 -0
- package/tools/synapse_qa_bench.py +190 -0
- package/tools/sync_agent_rules.py +274 -0
- package/tools/telemetry_correlator.py +397 -0
- package/tools/template_excel_exporter.py +514 -0
- package/tools/templates/jmeter-distributed/README.md +54 -0
- package/tools/templates/jmeter-distributed/docker-compose.yml +83 -0
- package/tools/test_impact.py +419 -0
- package/tools/test_memory_os.py +462 -0
- package/tools/textgrad_mutation_optimizer.py +237 -0
- package/tools/tms_sync_bridge.py +834 -0
- package/tools/tot_exploratory_tester.py +239 -0
- package/tools/trace_data_flow.py +240 -0
- package/tools/traffic_session_converter.py +256 -0
- package/tools/trend_analytics.py +314 -0
- package/tools/ui_server.py +401 -0
- package/tools/universal_ir.py +488 -0
- package/tools/update_sentinel.py +383 -0
- package/tools/validate_groovy_scripts.py +173 -0
- package/tools/verify_all.py +1271 -0
- package/tools/visual_diff_canvas.py +143 -0
- package/tools/visual_som_helper.py +550 -0
- package/tools/watch_mode.py +308 -0
- package/tools/wcag_audit.py +239 -0
- package/tools/welcome_page.py +290 -0
|
@@ -0,0 +1,538 @@
|
|
|
1
|
+
#!/usr/bin/env python3
|
|
2
|
+
# SPDX-FileCopyrightText: Copyright (c) Cloudflare, Inc.
|
|
3
|
+
# SPDX-FileCopyrightText: Copyright (c) 2026 Thế Vị (@TeeVee98). All rights reserved.
|
|
4
|
+
# SPDX-License-Identifier: MIT
|
|
5
|
+
# Adapted from cloudflare/security-audit-skill for Synapse-Hub Enterprise QA.
|
|
6
|
+
|
|
7
|
+
"""
|
|
8
|
+
Mathematical Security Coverage Ledger & Audit Tracker
|
|
9
|
+
-----------------------------------------------------
|
|
10
|
+
Manages and verifies formal audit coverage units across enterprise codebases:
|
|
11
|
+
Coverage Unit = Surface × Boundary × Subsystem × Attack Class [× Lifecycle]
|
|
12
|
+
|
|
13
|
+
Features:
|
|
14
|
+
1. RFC 3986 deterministic percent-encoded canonical coverage IDs.
|
|
15
|
+
2. Mathematical state tracking (planned, in_progress, covered, candidate, blocked, deferred, not_applicable, out_of_scope).
|
|
16
|
+
3. Full 19-field Cloudflare-compatible CoverageUnit schema.
|
|
17
|
+
4. Strict state machine invariant validation without external dependencies.
|
|
18
|
+
5. Dual document format support: top-level JSON array [...] and object {"units": [...]}.
|
|
19
|
+
6. Mathematical coverage and blocker rate metrics.
|
|
20
|
+
7. Safe identifier enforcement (anti-injection, Windows reserved device checks).
|
|
21
|
+
"""
|
|
22
|
+
|
|
23
|
+
from __future__ import annotations
|
|
24
|
+
|
|
25
|
+
import argparse
|
|
26
|
+
import json
|
|
27
|
+
import re
|
|
28
|
+
import sys
|
|
29
|
+
import urllib.parse
|
|
30
|
+
from dataclasses import asdict, dataclass, field
|
|
31
|
+
from pathlib import Path
|
|
32
|
+
from typing import Any, Dict, List, Optional, Set
|
|
33
|
+
|
|
34
|
+
# Enforce UTF-8 output encoding
|
|
35
|
+
if hasattr(sys.stdout, "reconfigure"):
|
|
36
|
+
try:
|
|
37
|
+
sys.stdout.reconfigure(encoding="utf-8")
|
|
38
|
+
sys.stderr.reconfigure(encoding="utf-8")
|
|
39
|
+
except Exception:
|
|
40
|
+
pass
|
|
41
|
+
|
|
42
|
+
VALID_STATUSES = {
|
|
43
|
+
"planned",
|
|
44
|
+
"in_progress",
|
|
45
|
+
"covered",
|
|
46
|
+
"candidate",
|
|
47
|
+
"blocked",
|
|
48
|
+
"deferred",
|
|
49
|
+
"out_of_scope",
|
|
50
|
+
"not_applicable",
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
WINDOWS_RESERVED_NAMES = {
|
|
54
|
+
"con",
|
|
55
|
+
"prn",
|
|
56
|
+
"aux",
|
|
57
|
+
"nul",
|
|
58
|
+
"com1",
|
|
59
|
+
"com2",
|
|
60
|
+
"com3",
|
|
61
|
+
"com4",
|
|
62
|
+
"com5",
|
|
63
|
+
"com6",
|
|
64
|
+
"com7",
|
|
65
|
+
"com8",
|
|
66
|
+
"com9",
|
|
67
|
+
"lpt1",
|
|
68
|
+
"lpt2",
|
|
69
|
+
"lpt3",
|
|
70
|
+
"lpt4",
|
|
71
|
+
"lpt5",
|
|
72
|
+
"lpt6",
|
|
73
|
+
"lpt7",
|
|
74
|
+
"lpt8",
|
|
75
|
+
"lpt9",
|
|
76
|
+
}
|
|
77
|
+
|
|
78
|
+
SAFE_ID_REGEX = re.compile(r"^[a-z0-9][a-z0-9._:-]{0,127}$", re.IGNORECASE)
|
|
79
|
+
|
|
80
|
+
|
|
81
|
+
def encode_canonical_ref(val: str) -> str:
|
|
82
|
+
"""RFC 3986 percent encoding: unreserved [A-Za-z0-9-._~] preserved, uppercase %XX for others."""
|
|
83
|
+
s = str(val).strip()
|
|
84
|
+
return urllib.parse.quote(s, safe="-._~")
|
|
85
|
+
|
|
86
|
+
|
|
87
|
+
@dataclass
|
|
88
|
+
class CoverageUnit:
|
|
89
|
+
coverage_id: str = ""
|
|
90
|
+
surface: str = ""
|
|
91
|
+
boundary: str = ""
|
|
92
|
+
subsystem: str = ""
|
|
93
|
+
attack_class: str = ""
|
|
94
|
+
status: str = "planned"
|
|
95
|
+
wave: int = 1
|
|
96
|
+
agent_id: Optional[str] = None
|
|
97
|
+
canonical_refs: Optional[Dict[str, str]] = None
|
|
98
|
+
starting_paths: List[str] = field(default_factory=list)
|
|
99
|
+
ordinary_attack_class_block: str = "ordinary"
|
|
100
|
+
selected_companion_blocks: List[str] = field(default_factory=list)
|
|
101
|
+
excluded_blocks: List[str] = field(default_factory=list)
|
|
102
|
+
prior_status: Optional[str] = None
|
|
103
|
+
attempts: int = 0
|
|
104
|
+
reviewed_paths: List[str] = field(default_factory=list)
|
|
105
|
+
local_checks: List[str] = field(default_factory=list)
|
|
106
|
+
result_fingerprints: List[str] = field(default_factory=list)
|
|
107
|
+
unresolved: List[str] = field(default_factory=list)
|
|
108
|
+
lifecycle: Optional[str] = None
|
|
109
|
+
notes: Optional[str] = None
|
|
110
|
+
|
|
111
|
+
def __post_init__(self):
|
|
112
|
+
if self.canonical_refs is None:
|
|
113
|
+
refs = {
|
|
114
|
+
"surface": self.surface,
|
|
115
|
+
"boundary": self.boundary,
|
|
116
|
+
"subsystem": self.subsystem,
|
|
117
|
+
"attack_class": self.attack_class,
|
|
118
|
+
}
|
|
119
|
+
if self.lifecycle:
|
|
120
|
+
refs["lifecycle"] = self.lifecycle
|
|
121
|
+
self.canonical_refs = refs
|
|
122
|
+
|
|
123
|
+
if not self.coverage_id:
|
|
124
|
+
self.coverage_id = CoverageLedgerManager.canonical_id(
|
|
125
|
+
self.surface, self.boundary, self.subsystem, self.attack_class, lifecycle=self.lifecycle
|
|
126
|
+
)
|
|
127
|
+
|
|
128
|
+
|
|
129
|
+
class CoverageLedgerManager:
|
|
130
|
+
"""Manages and validates coverage-ledger.json with mathematical rigor."""
|
|
131
|
+
|
|
132
|
+
def __init__(self, ledger_path: Path | str):
|
|
133
|
+
self.ledger_path = Path(ledger_path)
|
|
134
|
+
self.units: List[CoverageUnit] = []
|
|
135
|
+
self.format: str = "object" # 'object' | 'array'
|
|
136
|
+
if self.ledger_path.exists():
|
|
137
|
+
self.load()
|
|
138
|
+
|
|
139
|
+
@staticmethod
|
|
140
|
+
def canonical_id(
|
|
141
|
+
surface: str,
|
|
142
|
+
boundary: str,
|
|
143
|
+
subsystem: str,
|
|
144
|
+
attack_class: str,
|
|
145
|
+
lifecycle: Optional[str] = None,
|
|
146
|
+
) -> str:
|
|
147
|
+
"""Construct canonical deterministic coverage ID using RFC 3986 encoding."""
|
|
148
|
+
parts = [
|
|
149
|
+
encode_canonical_ref(s)
|
|
150
|
+
for s in (surface, boundary, subsystem, attack_class)
|
|
151
|
+
]
|
|
152
|
+
if lifecycle:
|
|
153
|
+
parts.append(encode_canonical_ref(lifecycle))
|
|
154
|
+
return "::".join(parts)
|
|
155
|
+
|
|
156
|
+
def load(self) -> None:
|
|
157
|
+
"""Load and parse ledger JSON supporting both array and object formats."""
|
|
158
|
+
try:
|
|
159
|
+
content = self.ledger_path.read_text(encoding="utf-8")
|
|
160
|
+
raw = json.loads(content)
|
|
161
|
+
if isinstance(raw, list):
|
|
162
|
+
self.format = "array"
|
|
163
|
+
units_data = raw
|
|
164
|
+
elif isinstance(raw, dict):
|
|
165
|
+
self.format = "object"
|
|
166
|
+
units_data = raw.get("units", [])
|
|
167
|
+
else:
|
|
168
|
+
raise ValueError("Expected JSON array or object with 'units'")
|
|
169
|
+
|
|
170
|
+
if not isinstance(units_data, list):
|
|
171
|
+
raise ValueError("Expected 'units' to be a list")
|
|
172
|
+
|
|
173
|
+
parsed: List[CoverageUnit] = []
|
|
174
|
+
for u in units_data:
|
|
175
|
+
if not isinstance(u, dict):
|
|
176
|
+
continue
|
|
177
|
+
# Filter out unknown keys safely
|
|
178
|
+
unit_args = {
|
|
179
|
+
k: v
|
|
180
|
+
for k, v in u.items()
|
|
181
|
+
if k in CoverageUnit.__dataclass_fields__
|
|
182
|
+
}
|
|
183
|
+
parsed.append(CoverageUnit(**unit_args))
|
|
184
|
+
self.units = parsed
|
|
185
|
+
except (json.JSONDecodeError, OSError, ValueError, TypeError, AttributeError) as err:
|
|
186
|
+
sys.stderr.write(f"[LEDGER] Error reading ledger file: {err}\n")
|
|
187
|
+
self.units = []
|
|
188
|
+
|
|
189
|
+
def save(self, format_type: Optional[str] = None) -> None:
|
|
190
|
+
"""Write units to ledger file with deterministic sorting and chosen format."""
|
|
191
|
+
fmt = format_type or self.format
|
|
192
|
+
self.ledger_path.parent.mkdir(parents=True, exist_ok=True)
|
|
193
|
+
sorted_units = sorted(self.units, key=lambda u: u.coverage_id)
|
|
194
|
+
units_dicts = [asdict(u) for u in sorted_units]
|
|
195
|
+
|
|
196
|
+
if fmt == "array":
|
|
197
|
+
content = json.dumps(units_dicts, indent=2, ensure_ascii=False)
|
|
198
|
+
else:
|
|
199
|
+
payload = {
|
|
200
|
+
"$schema": "synapse://schemas/v1/coverage-ledger.json",
|
|
201
|
+
"total_units": len(sorted_units),
|
|
202
|
+
"units": units_dicts,
|
|
203
|
+
}
|
|
204
|
+
content = json.dumps(payload, indent=2, ensure_ascii=False)
|
|
205
|
+
|
|
206
|
+
self.ledger_path.write_text(content, encoding="utf-8")
|
|
207
|
+
|
|
208
|
+
def add_unit(
|
|
209
|
+
self,
|
|
210
|
+
surface: str,
|
|
211
|
+
boundary: str,
|
|
212
|
+
subsystem: str,
|
|
213
|
+
attack_class: str,
|
|
214
|
+
lifecycle: Optional[str] = None,
|
|
215
|
+
wave: int = 1,
|
|
216
|
+
agent_id: Optional[str] = None,
|
|
217
|
+
status: str = "planned",
|
|
218
|
+
reviewed_paths: Optional[List[str]] = None,
|
|
219
|
+
local_checks: Optional[List[str]] = None,
|
|
220
|
+
result_fingerprints: Optional[List[str]] = None,
|
|
221
|
+
unresolved: Optional[List[str]] = None,
|
|
222
|
+
notes: Optional[str] = None,
|
|
223
|
+
) -> CoverageUnit:
|
|
224
|
+
"""Add or update a coverage unit."""
|
|
225
|
+
cov_id = self.canonical_id(
|
|
226
|
+
surface, boundary, subsystem, attack_class, lifecycle=lifecycle
|
|
227
|
+
)
|
|
228
|
+
for existing in self.units:
|
|
229
|
+
if existing.coverage_id == cov_id:
|
|
230
|
+
if wave != 1:
|
|
231
|
+
existing.wave = wave
|
|
232
|
+
if agent_id is not None:
|
|
233
|
+
existing.agent_id = agent_id
|
|
234
|
+
if status != "planned":
|
|
235
|
+
existing.status = status
|
|
236
|
+
if reviewed_paths is not None and len(reviewed_paths) > 0:
|
|
237
|
+
existing.reviewed_paths = reviewed_paths
|
|
238
|
+
if local_checks is not None and len(local_checks) > 0:
|
|
239
|
+
existing.local_checks = local_checks
|
|
240
|
+
if result_fingerprints is not None and len(result_fingerprints) > 0:
|
|
241
|
+
existing.result_fingerprints = result_fingerprints
|
|
242
|
+
if unresolved is not None and len(unresolved) > 0:
|
|
243
|
+
existing.unresolved = unresolved
|
|
244
|
+
if notes is not None:
|
|
245
|
+
existing.notes = notes
|
|
246
|
+
self.save()
|
|
247
|
+
return existing
|
|
248
|
+
|
|
249
|
+
refs = {
|
|
250
|
+
"surface": surface,
|
|
251
|
+
"boundary": boundary,
|
|
252
|
+
"subsystem": subsystem,
|
|
253
|
+
"attack_class": attack_class,
|
|
254
|
+
}
|
|
255
|
+
if lifecycle:
|
|
256
|
+
refs["lifecycle"] = lifecycle
|
|
257
|
+
|
|
258
|
+
unit = CoverageUnit(
|
|
259
|
+
coverage_id=cov_id,
|
|
260
|
+
surface=surface,
|
|
261
|
+
boundary=boundary,
|
|
262
|
+
subsystem=subsystem,
|
|
263
|
+
attack_class=attack_class,
|
|
264
|
+
status=status,
|
|
265
|
+
wave=wave,
|
|
266
|
+
agent_id=agent_id,
|
|
267
|
+
canonical_refs=refs,
|
|
268
|
+
reviewed_paths=reviewed_paths or [],
|
|
269
|
+
local_checks=local_checks or [],
|
|
270
|
+
result_fingerprints=result_fingerprints or [],
|
|
271
|
+
unresolved=unresolved or [],
|
|
272
|
+
lifecycle=lifecycle,
|
|
273
|
+
notes=notes,
|
|
274
|
+
)
|
|
275
|
+
self.units.append(unit)
|
|
276
|
+
self.save()
|
|
277
|
+
return unit
|
|
278
|
+
|
|
279
|
+
def validate(self) -> List[str]:
|
|
280
|
+
"""Validate all units against strict state machine and security invariants."""
|
|
281
|
+
errors: List[str] = []
|
|
282
|
+
seen_ids: Set[str] = set()
|
|
283
|
+
|
|
284
|
+
if len(self.units) > 10000:
|
|
285
|
+
errors.append("Ledger exceeds maximum limit of 10,000 units.")
|
|
286
|
+
|
|
287
|
+
for idx, u in enumerate(self.units, start=1):
|
|
288
|
+
base_label = f"Unit #{idx} ('{u.coverage_id}')"
|
|
289
|
+
|
|
290
|
+
# Check unique ID
|
|
291
|
+
if u.coverage_id in seen_ids:
|
|
292
|
+
errors.append(f"{base_label}: Duplicate coverage_id.")
|
|
293
|
+
seen_ids.add(u.coverage_id)
|
|
294
|
+
|
|
295
|
+
# Check status validity
|
|
296
|
+
if u.status not in VALID_STATUSES:
|
|
297
|
+
errors.append(
|
|
298
|
+
f"{base_label}: Invalid status '{u.status}'. Allowed: {sorted(list(VALID_STATUSES))}"
|
|
299
|
+
)
|
|
300
|
+
continue
|
|
301
|
+
|
|
302
|
+
# Check wave validity
|
|
303
|
+
if not isinstance(u.wave, int) or isinstance(u.wave, bool) or u.wave < 1:
|
|
304
|
+
errors.append(
|
|
305
|
+
f"{base_label}: Invalid wave '{u.wave}'. Wave must be an integer >= 1."
|
|
306
|
+
)
|
|
307
|
+
|
|
308
|
+
# Check agent_id safety
|
|
309
|
+
if u.agent_id:
|
|
310
|
+
agent_lower = u.agent_id.strip().lower()
|
|
311
|
+
if agent_lower in WINDOWS_RESERVED_NAMES:
|
|
312
|
+
errors.append(
|
|
313
|
+
f"{base_label}: agent_id '{u.agent_id}' is a Windows reserved device name."
|
|
314
|
+
)
|
|
315
|
+
if not SAFE_ID_REGEX.match(u.agent_id):
|
|
316
|
+
errors.append(
|
|
317
|
+
f"{base_label}: agent_id '{u.agent_id}' contains invalid characters."
|
|
318
|
+
)
|
|
319
|
+
|
|
320
|
+
# Check canonical consistency
|
|
321
|
+
expected_id = self.canonical_id(
|
|
322
|
+
u.surface, u.boundary, u.subsystem, u.attack_class, lifecycle=u.lifecycle
|
|
323
|
+
)
|
|
324
|
+
if u.coverage_id != expected_id:
|
|
325
|
+
errors.append(
|
|
326
|
+
f"{base_label}: ID does not match RFC 3986 canonical formula '{expected_id}'"
|
|
327
|
+
)
|
|
328
|
+
|
|
329
|
+
# Check result_fingerprints exclusivity (only 'candidate' units can have fingerprints)
|
|
330
|
+
if u.status != "candidate" and u.result_fingerprints:
|
|
331
|
+
errors.append(
|
|
332
|
+
f"{base_label}: Unit with status '{u.status}' must have empty result_fingerprints."
|
|
333
|
+
)
|
|
334
|
+
|
|
335
|
+
# State Machine Invariant Verification
|
|
336
|
+
if u.status == "planned":
|
|
337
|
+
if u.agent_id is not None:
|
|
338
|
+
errors.append(f"{base_label}: Planned unit must be unassigned (agent_id must be None).")
|
|
339
|
+
if u.reviewed_paths:
|
|
340
|
+
errors.append(f"{base_label}: Planned unit must have empty reviewed_paths.")
|
|
341
|
+
if u.local_checks:
|
|
342
|
+
errors.append(f"{base_label}: Planned unit must have empty local_checks.")
|
|
343
|
+
if u.unresolved:
|
|
344
|
+
errors.append(f"{base_label}: Planned unit must have empty unresolved list.")
|
|
345
|
+
|
|
346
|
+
elif u.status == "in_progress":
|
|
347
|
+
if not u.agent_id:
|
|
348
|
+
errors.append(f"{base_label}: In-progress unit requires an assigned agent_id.")
|
|
349
|
+
if u.reviewed_paths:
|
|
350
|
+
errors.append(f"{base_label}: In-progress unit must have empty reviewed_paths before completion.")
|
|
351
|
+
if u.local_checks:
|
|
352
|
+
errors.append(f"{base_label}: In-progress unit must have empty local_checks before completion.")
|
|
353
|
+
if u.unresolved:
|
|
354
|
+
errors.append(f"{base_label}: In-progress unit must have empty unresolved list.")
|
|
355
|
+
|
|
356
|
+
elif u.status == "covered":
|
|
357
|
+
if not u.agent_id:
|
|
358
|
+
errors.append(f"{base_label}: Covered unit requires an assigned agent_id.")
|
|
359
|
+
if not u.reviewed_paths:
|
|
360
|
+
errors.append(f"{base_label}: Covered unit requires non-empty reviewed_paths.")
|
|
361
|
+
if not u.local_checks:
|
|
362
|
+
errors.append(f"{base_label}: Covered unit requires non-empty local_checks.")
|
|
363
|
+
if u.unresolved:
|
|
364
|
+
errors.append(f"{base_label}: Covered unit must have empty unresolved list.")
|
|
365
|
+
|
|
366
|
+
elif u.status == "candidate":
|
|
367
|
+
if not u.agent_id:
|
|
368
|
+
errors.append(f"{base_label}: Candidate finding unit requires an assigned agent_id.")
|
|
369
|
+
if not u.reviewed_paths:
|
|
370
|
+
errors.append(f"{base_label}: Candidate finding unit requires non-empty reviewed_paths.")
|
|
371
|
+
if not u.local_checks:
|
|
372
|
+
errors.append(f"{base_label}: Candidate finding unit requires non-empty local_checks.")
|
|
373
|
+
if not u.result_fingerprints:
|
|
374
|
+
errors.append(f"{base_label}: Candidate finding unit requires non-empty result_fingerprints.")
|
|
375
|
+
|
|
376
|
+
elif u.status == "blocked":
|
|
377
|
+
if not u.agent_id:
|
|
378
|
+
errors.append(f"{base_label}: Blocked unit requires an assigned agent_id.")
|
|
379
|
+
if not u.reviewed_paths:
|
|
380
|
+
errors.append(f"{base_label}: Blocked unit requires reviewed_paths to establish blockage context.")
|
|
381
|
+
if not u.local_checks:
|
|
382
|
+
errors.append(f"{base_label}: Blocked unit requires local_checks to establish blockage context.")
|
|
383
|
+
if not u.unresolved:
|
|
384
|
+
errors.append(f"{base_label}: Blocked unit requires non-empty unresolved explanations.")
|
|
385
|
+
|
|
386
|
+
elif u.status in {"deferred", "out_of_scope", "not_applicable"}:
|
|
387
|
+
if u.agent_id is not None:
|
|
388
|
+
errors.append(f"{base_label}: Unit with status '{u.status}' must be unassigned.")
|
|
389
|
+
if u.reviewed_paths:
|
|
390
|
+
errors.append(f"{base_label}: Unit with status '{u.status}' must have empty reviewed_paths.")
|
|
391
|
+
if u.local_checks:
|
|
392
|
+
errors.append(f"{base_label}: Unit with status '{u.status}' must have empty local_checks.")
|
|
393
|
+
if not u.unresolved:
|
|
394
|
+
errors.append(f"{base_label}: Unit with status '{u.status}' must state reason in unresolved list.")
|
|
395
|
+
|
|
396
|
+
return errors
|
|
397
|
+
|
|
398
|
+
def get_metrics(self) -> Dict[str, Any]:
|
|
399
|
+
"""Compute mathematical coverage metrics across all units."""
|
|
400
|
+
total = len(self.units)
|
|
401
|
+
status_counts = {s: 0 for s in VALID_STATUSES}
|
|
402
|
+
wave_counts: Dict[int, int] = {}
|
|
403
|
+
|
|
404
|
+
for u in self.units:
|
|
405
|
+
status_counts[u.status] = status_counts.get(u.status, 0) + 1
|
|
406
|
+
wave_counts[u.wave] = wave_counts.get(u.wave, 0) + 1
|
|
407
|
+
|
|
408
|
+
out_of_scope = status_counts.get("out_of_scope", 0)
|
|
409
|
+
not_applicable = status_counts.get("not_applicable", 0)
|
|
410
|
+
in_scope = total - out_of_scope - not_applicable
|
|
411
|
+
|
|
412
|
+
covered = status_counts.get("covered", 0)
|
|
413
|
+
candidate = status_counts.get("candidate", 0)
|
|
414
|
+
audited = covered + candidate
|
|
415
|
+
blocked = status_counts.get("blocked", 0)
|
|
416
|
+
|
|
417
|
+
coverage_pct = round((audited / in_scope * 100.0), 2) if in_scope > 0 else 0.0
|
|
418
|
+
blocker_rate_pct = round((blocked / in_scope * 100.0), 2) if in_scope > 0 else 0.0
|
|
419
|
+
|
|
420
|
+
return {
|
|
421
|
+
"total_units": total,
|
|
422
|
+
"in_scope_units": in_scope,
|
|
423
|
+
"audited_units": audited,
|
|
424
|
+
"audited_coverage_pct": coverage_pct,
|
|
425
|
+
"blocker_rate_pct": blocker_rate_pct,
|
|
426
|
+
"status_breakdown": status_counts,
|
|
427
|
+
"wave_breakdown": wave_counts,
|
|
428
|
+
}
|
|
429
|
+
|
|
430
|
+
def get_summary(self) -> Dict[str, int]:
|
|
431
|
+
"""Return basic status breakdown for backward-compatibility."""
|
|
432
|
+
counts = {s: 0 for s in VALID_STATUSES}
|
|
433
|
+
for u in self.units:
|
|
434
|
+
counts[u.status] = counts.get(u.status, 0) + 1
|
|
435
|
+
return counts
|
|
436
|
+
|
|
437
|
+
|
|
438
|
+
def main():
|
|
439
|
+
parser = argparse.ArgumentParser(
|
|
440
|
+
description="Mathematical Security Coverage Ledger Manager (Cloudflare Pattern)"
|
|
441
|
+
)
|
|
442
|
+
subparsers = parser.add_subparsers(dest="command")
|
|
443
|
+
|
|
444
|
+
# init
|
|
445
|
+
init_parser = subparsers.add_parser("init", help="Initialize a new ledger")
|
|
446
|
+
init_parser.add_argument(
|
|
447
|
+
"--file", "-f", default="coverage-ledger.json", help="Ledger output path"
|
|
448
|
+
)
|
|
449
|
+
init_parser.add_argument(
|
|
450
|
+
"--format", choices=["array", "object"], default="object", help="Document format (array or object)"
|
|
451
|
+
)
|
|
452
|
+
|
|
453
|
+
# validate
|
|
454
|
+
val_parser = subparsers.add_parser("validate", help="Validate an existing ledger")
|
|
455
|
+
val_parser.add_argument("file", help="Ledger path")
|
|
456
|
+
|
|
457
|
+
# add
|
|
458
|
+
add_parser = subparsers.add_parser("add", help="Add a unit")
|
|
459
|
+
add_parser.add_argument("--file", "-f", default="coverage-ledger.json")
|
|
460
|
+
add_parser.add_argument("--surface", "-s", required=True)
|
|
461
|
+
add_parser.add_argument("--boundary", "-b", required=True)
|
|
462
|
+
add_parser.add_argument("--subsystem", required=True)
|
|
463
|
+
add_parser.add_argument("--attack-class", "-a", required=True)
|
|
464
|
+
add_parser.add_argument("--lifecycle", default=None)
|
|
465
|
+
add_parser.add_argument("--wave", type=int, default=1)
|
|
466
|
+
add_parser.add_argument("--agent-id", default=None)
|
|
467
|
+
add_parser.add_argument("--status", default="planned")
|
|
468
|
+
add_parser.add_argument("--reviewed-paths", nargs="*", default=[])
|
|
469
|
+
add_parser.add_argument("--local-checks", nargs="*", default=[])
|
|
470
|
+
add_parser.add_argument("--unresolved", nargs="*", default=[])
|
|
471
|
+
add_parser.add_argument("--result-fingerprints", nargs="*", default=[])
|
|
472
|
+
add_parser.add_argument("--notes", default=None)
|
|
473
|
+
|
|
474
|
+
# summary
|
|
475
|
+
sum_parser = subparsers.add_parser("summary", help="Print summary metrics")
|
|
476
|
+
sum_parser.add_argument("file", help="Ledger path")
|
|
477
|
+
sum_parser.add_argument("--json", action="store_true", help="Output summary as JSON")
|
|
478
|
+
|
|
479
|
+
args = parser.parse_args()
|
|
480
|
+
|
|
481
|
+
if args.command == "init":
|
|
482
|
+
mgr = CoverageLedgerManager(args.file)
|
|
483
|
+
mgr.save(format_type=args.format)
|
|
484
|
+
print(f"✨ Initialized empty coverage ledger ({args.format} format) at: {args.file}")
|
|
485
|
+
elif args.command == "add":
|
|
486
|
+
mgr = CoverageLedgerManager(args.file)
|
|
487
|
+
unit = mgr.add_unit(
|
|
488
|
+
surface=args.surface,
|
|
489
|
+
boundary=args.boundary,
|
|
490
|
+
subsystem=args.subsystem,
|
|
491
|
+
attack_class=args.attack_class,
|
|
492
|
+
lifecycle=args.lifecycle,
|
|
493
|
+
wave=args.wave,
|
|
494
|
+
agent_id=args.agent_id,
|
|
495
|
+
status=args.status,
|
|
496
|
+
reviewed_paths=args.reviewed_paths,
|
|
497
|
+
local_checks=args.local_checks,
|
|
498
|
+
result_fingerprints=args.result_fingerprints,
|
|
499
|
+
unresolved=args.unresolved,
|
|
500
|
+
notes=args.notes,
|
|
501
|
+
)
|
|
502
|
+
print(f"✅ Added coverage unit: {unit.coverage_id} [{unit.status}]")
|
|
503
|
+
elif args.command == "validate":
|
|
504
|
+
mgr = CoverageLedgerManager(args.file)
|
|
505
|
+
errors = mgr.validate()
|
|
506
|
+
if errors:
|
|
507
|
+
print(f"❌ Validation failed with {len(errors)} error(s):")
|
|
508
|
+
for err in errors:
|
|
509
|
+
print(f" - {err}")
|
|
510
|
+
sys.exit(1)
|
|
511
|
+
else:
|
|
512
|
+
print(f"✅ Ledger valid! {len(mgr.units)} units inspected with zero violations.")
|
|
513
|
+
elif args.command == "summary":
|
|
514
|
+
mgr = CoverageLedgerManager(args.file)
|
|
515
|
+
metrics = mgr.get_metrics()
|
|
516
|
+
if args.json:
|
|
517
|
+
print(json.dumps(metrics, indent=2, ensure_ascii=False))
|
|
518
|
+
else:
|
|
519
|
+
print(f"📊 Security Coverage Ledger Metrics ({metrics['total_units']} total units):")
|
|
520
|
+
print(f" - In-Scope Units: {metrics['in_scope_units']}")
|
|
521
|
+
print(f" - Audited Coverage: {metrics['audited_coverage_pct']}% ({metrics['audited_units']}/{metrics['in_scope_units']} units)")
|
|
522
|
+
print(f" - Blocker Rate: {metrics['blocker_rate_pct']}%")
|
|
523
|
+
print(" Status Breakdown:")
|
|
524
|
+
for status, count in metrics["status_breakdown"].items():
|
|
525
|
+
print(f" - {status.upper():16s}: {count}")
|
|
526
|
+
print(" Wave Breakdown:")
|
|
527
|
+
sorted_waves = sorted(
|
|
528
|
+
metrics["wave_breakdown"].items(),
|
|
529
|
+
key=lambda item: (0, item[0]) if isinstance(item[0], int) else (1, str(item[0])),
|
|
530
|
+
)
|
|
531
|
+
for wave, count in sorted_waves:
|
|
532
|
+
print(f" - Wave {str(wave):<11s}: {count}")
|
|
533
|
+
else:
|
|
534
|
+
parser.print_help()
|
|
535
|
+
|
|
536
|
+
|
|
537
|
+
if __name__ == "__main__":
|
|
538
|
+
main()
|