.bestpractices.json

{
  "$schema": "https://bestpractices.coreinfrastructure.org/projects.schema.json",
  "_comment": "OpenSSF Best Practices self-assessment for RandomCodeSpace/docsiq. Project is registered (id 12628) and the badge currently displays 'passing' — see https://www.bestpractices.dev/en/projects/12628. The audit_* fields below mirror the per-criterion answers submitted to the OpenSSF Best Practices site; refresh them whenever criteria scoring changes.",
  "project_id": 12628,
  "name": "docsiq",
  "description": "GraphRAG-powered documentation search tool — indexes PDF/DOCX/TXT/MD/web content into a knowledge graph with entity extraction, community detection, and vector embeddings, then answers queries via graph + vector search.",
  "homepage_url": "https://github.com/RandomCodeSpace/docsiq",
  "repo_url": "https://github.com/RandomCodeSpace/docsiq",
  "license": "MIT",
  "level": "passing",
  "badge_url": "https://www.bestpractices.dev/projects/12628/badge",
  "project_page_url": "https://www.bestpractices.dev/en/projects/12628",
  "evidence": {
    "vulnerability_report_process": "SECURITY.md",
    "license_file": "LICENSE",
    "code_of_conduct": "CODE_OF_CONDUCT.md",
    "contributing_guide": "CONTRIBUTING.md",
    "governance": "GOVERNANCE.md",
    "build_reproducible": "go build -tags sqlite_fts5 ./...",
    "ci_workflow": ".github/workflows/ci.yml",
    "code_scanning": ".github/workflows/codeql.yml",
    "supply_chain_scorecard": ".github/workflows/scorecard.yml",
    "oss_cli_security_stack": ".github/workflows/security.yml",
    "fuzz_testing": ".github/workflows/fuzz.yml",
    "dependency_updates": ".github/dependabot.yml",
    "secret_scanning": "GitHub repo setting (secret_scanning + push_protection enabled)",
    "private_vulnerability_reporting": "GitHub repo setting (security advisories enabled)",
    "signed_releases": "cosign keyless signing via .github/workflows/release.yml + Sigstore Rekor"
  },
  "audit": {
    "self_assessment_date": "2026-04-26",
    "self_assessment_author": "TechLead (RAN-51)",
    "ran_50_lane": "RAN-51 (recipe validation; replicates to otelcontext, snipIT, vigil)",
    "scorecard_dashboard": "https://scorecard.dev/viewer/?uri=github.com/RandomCodeSpace/docsiq"
  },

  "description_good_status": "Met",
  "description_good_justification": "See README.md. docsiq is a GraphRAG-powered documentation search tool written in Go that indexes PDF/DOCX/TXT/MD/web content into a knowledge graph with entity extraction, community detection, and vector embeddings, then answers queries via graph + vector search. https://github.com/RandomCodeSpace/docsiq/blob/main/README.md",

  "interact_status": "Met",
  "interact_justification": "GitHub Issues for bug reports, GitHub Discussions for questions, SECURITY.md for private vulnerability reports. All linked from README. https://github.com/RandomCodeSpace/docsiq/issues",

  "contribution_status": "Met",
  "contribution_justification": "https://github.com/RandomCodeSpace/docsiq/blob/main/CONTRIBUTING.md",

  "contribution_requirements_status": "Met",
  "contribution_requirements_justification": "CONTRIBUTING.md documents PR requirements: go test suite passing, go vet clean, CodeQL passing, Conventional Commit style. https://github.com/RandomCodeSpace/docsiq/blob/main/CONTRIBUTING.md",

  "documentation_interface_status": "Met",
  "documentation_interface_justification": "CLI interface documented in docs/cli-reference.md; REST API documented in docs/rest-api.md; MCP tool catalogue in docs/mcp-tools.md. https://github.com/RandomCodeSpace/docsiq/tree/main/docs",

  "test_continuous_integration_status": "Met",
  "test_continuous_integration_justification": "CI runs full test suite (unit + integration + fuzz) on every PR and every push to main. https://github.com/RandomCodeSpace/docsiq/blob/main/.github/workflows/ci.yml",

  "license_location_status": "Met",
  "license_location_justification": "https://github.com/RandomCodeSpace/docsiq/blob/main/LICENSE",

  "floss_license_status": "Met",
  "floss_license_justification": "MIT — https://opensource.org/licenses/MIT",

  "floss_license_osi_status": "Met",
  "floss_license_osi_justification": "MIT is OSI-approved.",

  "english_status": "Met",
  "english_justification": "All source comments, documentation, commit messages, and issue discussions are in English.",

  "repo_public_status": "Met",
  "repo_public_justification": "https://github.com/RandomCodeSpace/docsiq",

  "repo_track_status": "Met",
  "repo_track_justification": "Git, hosted on GitHub. https://github.com/RandomCodeSpace/docsiq",

  "repo_interim_status": "Met",
  "repo_interim_justification": "All commits merged to main are publicly visible. No batch or secret merges.",

  "repo_distributed_status": "Met",
  "repo_distributed_justification": "Git is a distributed VCS; every clone holds full history.",

  "version_unique_status": "Met",
  "version_unique_justification": "Each release carries a unique semver tag (v0.0.1, v0.0.2, ...) and an immutable git SHA.",

  "version_semver_status": "Met",
  "version_semver_justification": "MAJOR.MINOR.PATCH. Release workflow accepts a bump choice (major/minor/patch) and computes next tag from the latest stable. https://github.com/RandomCodeSpace/docsiq/blob/main/.github/workflows/release.yml",

  "version_tags_status": "Met",
  "version_tags_justification": "https://github.com/RandomCodeSpace/docsiq/tags",

  "release_notes_status": "Met",
  "release_notes_justification": "https://github.com/RandomCodeSpace/docsiq/blob/main/CHANGELOG.md",

  "report_process_status": "Met",
  "report_process_justification": "https://github.com/RandomCodeSpace/docsiq/blob/main/SECURITY.md",

  "report_tracker_status": "Met",
  "report_tracker_justification": "https://github.com/RandomCodeSpace/docsiq/issues",

  "report_responses_status": "Met",
  "report_responses_justification": "Maintainer responds to reported issues within 14 days; recent issue history confirms this.",

  "enhancement_responses_status": "Met",
  "enhancement_responses_justification": "Enhancement requests receive a triage response within 14 days.",

  "vulnerability_report_process_status": "Met",
  "vulnerability_report_process_justification": "https://github.com/RandomCodeSpace/docsiq/blob/main/SECURITY.md",

  "vulnerability_report_private_status": "Met",
  "vulnerability_report_private_justification": "GitHub private vulnerability reporting is enabled on the repo. https://github.com/RandomCodeSpace/docsiq/security/advisories",

  "vulnerability_report_response_status": "Met",
  "vulnerability_report_response_justification": "SECURITY.md commits to 72h initial response and 14-day triage.",

  "build_status": "Met",
  "build_justification": "Single-command build: `go build -tags sqlite_fts5 ./` or `make build`. CI builds every PR. https://github.com/RandomCodeSpace/docsiq/blob/main/.github/workflows/ci.yml",

  "build_common_tools_status": "Met",
  "build_common_tools_justification": "Go toolchain + npm (UI). Both are widely available and standard.",

  "build_floss_tools_status": "Met",
  "build_floss_tools_justification": "Go (BSD-3-Clause), Node/npm (MIT), Make (GPL). All FLOSS.",

  "test_status": "Met",
  "test_justification": "Automated test suite runs on every push. https://github.com/RandomCodeSpace/docsiq/actions/workflows/ci.yml",

  "test_invocation_status": "Met",
  "test_invocation_justification": "`go test ./...` — documented in README and CONTRIBUTING.md.",

  "test_most_status": "Met",
  "test_most_justification": "Unit and integration tests across internal/api, internal/notes, internal/crawler, internal/chunker, internal/vectorindex, internal/store, and more.",

  "test_policy_status": "Met",
  "test_policy_justification": "CONTRIBUTING.md requires tests for new features and regression tests for bug fixes. PR review enforces it.",

  "tests_are_added_status": "Met",
  "tests_are_added_justification": "Recent PRs (#19, #28, #32, #44) each added tests alongside code changes.",

  "tests_documented_added_status": "Met",
  "tests_documented_added_justification": "CONTRIBUTING.md documents the test-with-every-change expectation.",

  "warnings_status": "Met",
  "warnings_justification": "`go vet ./...` and `golangci-lint` run on every CI build; any warning fails the build.",

  "warnings_fixed_status": "Met",
  "warnings_fixed_justification": "All vet/lint warnings resolved on main; no suppressions without justification.",

  "warnings_strict_status": "Met",
  "warnings_strict_justification": "CI fails on any vet or golangci-lint warning — effectively -Werror.",

  "know_secure_design_status": "Met",
  "know_secure_design_justification": "Maintainer applies defense-in-depth: path-injection sanitisers at user-data boundaries (filepath.IsLocal in internal/api/project.go and internal/notes/history.go), least-privilege file perms (0o600/0o700 via PR #19), sandboxed git invocations (GIT_CONFIG_GLOBAL=/dev/null in internal/notes/history.go).",

  "know_common_errors_status": "Met",
  "know_common_errors_justification": "Familiar with OWASP Top 10, CWE-22/78/79/89/918. CodeQL security-extended suite enabled; all findings triaged to closure. https://github.com/RandomCodeSpace/docsiq/security/code-scanning",

  "crypto_published_status": "Met",
  "crypto_published_justification": "Only published algorithms used: Go crypto/tls, crypto/rand, crypto/sha256. No custom crypto.",

  "crypto_call_status": "Met",
  "crypto_call_justification": "All outbound HTTPS via Go stdlib crypto/tls; system trust store; TLS 1.2+.",

  "crypto_floss_status": "Met",
  "crypto_floss_justification": "Go standard library crypto (BSD-3-Clause). Sigstore cosign (Apache-2.0).",

  "crypto_keylength_status": "Met",
  "crypto_keylength_justification": "Go stdlib defaults: RSA ≥2048-bit / P-256 ECDSA / SHA-256. No weak keys.",

  "crypto_working_status": "Met",
  "crypto_working_justification": "No MD5/SHA-1 for integrity. No DES/RC4. Only AEAD ciphers via stdlib defaults.",

  "crypto_weaknesses_status": "Met",
  "crypto_weaknesses_justification": "Sigstore cosign signing uses ECDSA-P256 + SHA-256. Go TLS defaults exclude weak primitives.",

  "crypto_pfs_status": "Met",
  "crypto_pfs_justification": "Go stdlib default TLS ciphersuites are AEAD + ECDHE — forward secrecy by default.",

  "crypto_random_status": "Met",
  "crypto_random_justification": "All randomness via crypto/rand (CSPRNG). No math/rand for security-sensitive values.",

  "delivery_mitm_status": "Met",
  "delivery_mitm_justification": "Release assets downloaded over HTTPS from github.com. Integrity verifiable via published SHA256SUMS and cosign signatures.",

  "delivery_unsigned_status": "Met",
  "delivery_unsigned_justification": "Every release vX.Y.Z ships cosign keyless-signed binaries (Sigstore OIDC) + signed SHA256SUMS + SLSA build provenance. Scorecard Signed-Releases = 10/10. https://github.com/RandomCodeSpace/docsiq/releases/latest",

  "vulnerabilities_fixed_60_days_status": "Met",
  "vulnerabilities_fixed_60_days_justification": "No known unfixed vulns. Dependabot auto-opens PRs for CVEs; CodeQL and govulncheck run on every push. https://github.com/RandomCodeSpace/docsiq/security/advisories",

  "vulnerabilities_critical_fixed_status": "Met",
  "vulnerabilities_critical_fixed_justification": "Zero High/Critical open. Recent Medium fixes in PR #19 (file perms, URL scheme allow-list) and PR #44 (path-injection sanitisers).",

  "no_leaked_credentials_status": "Met",
  "no_leaked_credentials_justification": "GitHub push-protection and secret-scanning enabled repo-wide. No secrets in code or history.",

  "static_analysis_status": "Met",
  "static_analysis_justification": "CodeQL on every PR and push to main. https://github.com/RandomCodeSpace/docsiq/security/code-scanning",

  "static_analysis_common_vulnerabilities_status": "Met",
  "static_analysis_common_vulnerabilities_justification": "CodeQL 'security-extended' query suite covers CWE-22/78/79/89/918 and the rest of the CWE Top 25.",

  "static_analysis_fixed_status": "Met",
  "static_analysis_fixed_justification": "All Medium+ findings fixed or dismissed with explicit justification. Zero open.",

  "static_analysis_often_status": "Met",
  "static_analysis_often_justification": "On every push to main and every PR.",

  "dynamic_analysis_status": "Met",
  "dynamic_analysis_justification": "Native Go fuzzing: FuzzResolveURL (crawler), FuzzChunker. CI runs each for 30s per push. https://github.com/RandomCodeSpace/docsiq/blob/main/.github/workflows/fuzz.yml",

  "dynamic_analysis_unsafe_status": "Met",
  "dynamic_analysis_unsafe_justification": "Go is memory-safe; no unsafe.Pointer in application code. -race detector is enabled for concurrency-sensitive packages (see internal/vectorindex/race_on.go).",

  "dynamic_analysis_enable_assertions_status": "Met",
  "dynamic_analysis_enable_assertions_justification": "Go panics-on-invariants used throughout; -race detector is the Go equivalent of runtime assertions for concurrency.",

  "dynamic_analysis_fixed_status": "Met",
  "dynamic_analysis_fixed_justification": "Fuzzing-discovered http/https allow-list bypass fixed in PR #19 same day.",

  "installation_common_status": "Met",
  "installation_common_justification": "`go install github.com/RandomCodeSpace/docsiq@latest` or download signed binary from Releases. Documented in README.",

  "installation_standard_variables_status": "Met",
  "installation_standard_variables_justification": "Config uses DOCSIQ_* env prefix and ~/.docsiq/ config dir — follows XDG convention.",

  "installation_development_quick_status": "Met",
  "installation_development_quick_justification": "`make build` or `go build -tags sqlite_fts5 ./` — documented in README.",

  "maintained_status": "Met",
  "maintained_justification": "Active development: releases v0.0.1 and v0.0.2 cut in the last 30 days. Continuous PR activity. Dependabot + CodeQL automation running.",

  "achievements_justified_status": "Met",
  "achievements_justified_justification": "Each claim backed by CI artifacts and Scorecard report: https://scorecard.dev/viewer/?uri=github.com/RandomCodeSpace/docsiq",

  "hardening_headers_status": "Met",
  "hardening_headers_justification": "API handlers set Content-Type: application/json and X-Content-Type-Options: nosniff globally. Embedded SPA served with restrictive CSP.",

  "crypto_used_network_status": "Met",
  "crypto_used_network_justification": "All external calls (LLM providers — Azure/OpenAI/Ollama) over HTTPS via Go stdlib.",

  "implement_secure_design_status": "Met",
  "implement_secure_design_justification": "Path-injection sanitisers (filepath.IsLocal) at every user-data boundary: internal/api/project.go:82, internal/notes/history.go, internal/notes/notes.go.",

  "discussion_status": "Met",
  "discussion_justification": "https://github.com/RandomCodeSpace/docsiq/discussions",

  "sites_https_status": "Met",
  "sites_https_justification": "All project links (README, docs, release downloads) use HTTPS via github.com.",

  "crypto_password_storage_status": "N/A",
  "crypto_password_storage_justification": "N/A — docsiq stores no user passwords. It's a local single-user indexer with no auth system.",

  "crypto_certificate_verification_status": "N/A",
  "crypto_certificate_verification_justification": "N/A — only outbound HTTPS via Go stdlib (which verifies certificates by default). We don't issue or pin certificates.",

  "copyright_per_file_status": "N/A",
  "copyright_per_file_justification": "N/A — single MIT LICENSE at repo root covers all files. Standard practice for single-author OSS.",

  "license_per_file_status": "N/A",
  "license_per_file_justification": "N/A — single MIT LICENSE at repo root covers all files.",

  "delivery_pgp_signed_status": "N/A",
  "delivery_pgp_signed_justification": "N/A — uses Sigstore cosign keyless signing (OIDC) instead of PGP, the modern SLSA-recommended approach. Verification via `cosign verify-blob` + Rekor transparency log.",

  "sites_sniff_protection_status": "N/A",
  "sites_sniff_protection_justification": "N/A — project has no public web service. Documentation hosted on GitHub, which ships hardened headers by default.",

  "crypto_published_algorithms_status": "N/A",
  "crypto_published_algorithms_justification": "N/A — no custom cryptography is implemented. Only Go stdlib and Sigstore cosign.",

  "installation_standard_status": "N/A",
  "installation_standard_justification": "N/A — single-file Go binary, no OS-specific packaging (.deb, .rpm) planned at passing tier. Homebrew tap is a silver-tier goal.",

  "build_standard_variables_status": "N/A",
  "build_standard_variables_justification": "N/A — no compiler-level env vars beyond GOOS / GOARCH / CGO_ENABLED, which are Go conventions.",

  "sites_password_security_status": "N/A",
  "sites_password_security_justification": "N/A — no user accounts or passwords. Maintainer auth handled by GitHub.",

  "code_of_conduct_status": "Met",
  "code_of_conduct_justification": "Contributor Covenant 2.1 adopted. https://github.com/RandomCodeSpace/docsiq/blob/main/CODE_OF_CONDUCT.md",

  "governance_status": "Met",
  "governance_justification": "Lead-maintainer model documented with decision-making process, roles, and continuity plan. https://github.com/RandomCodeSpace/docsiq/blob/main/GOVERNANCE.md",

  "roles_responsibilities_status": "Met",
  "roles_responsibilities_justification": "Lead maintainer, security contact, and reviewer roles documented. https://github.com/RandomCodeSpace/docsiq/blob/main/GOVERNANCE.md#roles",

  "access_continuity_status": "Met",
  "access_continuity_justification": ".github/CODEOWNERS routes PR review to @aksOps; GOVERNANCE.md documents admin-access continuity via reproducible builds and cosign keyless signing. https://github.com/RandomCodeSpace/docsiq/blob/main/.github/CODEOWNERS",

  "bus_factor_status": "Met",
  "bus_factor_justification": "Single-maintainer risk mitigated by reproducible builds and keyless cosign signing anchored to GitHub OIDC + Rekor — not a private key. Any fork can reproduce identical release artifacts. https://github.com/RandomCodeSpace/docsiq/blob/main/GOVERNANCE.md#continuity-and-resilience",

  "report_archive_status": "Met",
  "report_archive_justification": "GitHub Issues serves as the public report archive; Security Advisories archive coordinated-disclosure reports. https://github.com/RandomCodeSpace/docsiq/blob/main/SECURITY.md#report-archive",

  "release_notes_vulns_status": "Met",
  "release_notes_vulns_justification": ".github/release.yml defines a 'Security fixes' section auto-populated from PRs labelled `security` in GitHub-generated release notes. https://github.com/RandomCodeSpace/docsiq/blob/main/.github/release.yml",

  "accessibility_best_practices_status": "Met",
  "accessibility_best_practices_justification": "WCAG 2.1 Level AA stance documented for the embedded React SPA: contrast ≥ 4.5:1, keyboard nav, prefers-reduced-motion, semantic HTML, axe-core checks. https://github.com/RandomCodeSpace/docsiq/blob/main/docs/ACCESSIBILITY.md"
}