OpenSSF Best Practices — Silver Tier Justifications

Project: Aigis (BadgeApp project #12808) · Repository: github.com/killertcell428/aigis · Compiled 2026-05-12

各 Silver 項目について、BadgeApp フォームの「justification」欄にそのまま貼り付けるテキストと、 リポジトリ内の証拠ファイルへのリンクを列挙したリファレンス。 Passing tier の達成項目は openssf-best-practices.md を参照。

~46Met (justification準備済)
3Partial（短期内に解消）
2Known Gap（bus_factor / coverage 80%）
4N/A（該当なし選択）
目次

1. Basics（基本的情報）

dco — Developer Certificate of Origin MET
Evidence:
The project requires a Developer Certificate of Origin sign-off on every commit. Contributors must add `Signed-off-by: Name <email>` (via `git commit -s`). A GitHub Actions workflow (.github/workflows/dco.yml) runs `tim-actions/dco` on every pull request and blocks merging when any commit lacks a valid sign-off. The policy and how-to are documented in CONTRIBUTING.md.
governance MET
Evidence:
GOVERNANCE.md documents the decision-making process, maintainer roles, how to become a maintainer, tiebreaker rules, and how maintainers are added or removed. The file is in the repository root for visibility.
code_of_conduct MET
Evidence:
The project adopts the Contributor Covenant 2.1 (CODE_OF_CONDUCT.md at the repository root). GitHub renders this in the Community Standards page and links it from new-issue templates.
roles_responsibilities MET
Evidence:
GOVERNANCE.md defines the project roles (Maintainer, Contributor, Reporter) with explicit responsibilities and the path for promotion. The current maintainer roster is enumerated in GOVERNANCE.md and reflected in GitHub repository permissions.
access_continuity MET
Evidence:
docs/access_continuity.md inventories every credential/account the project relies on (GitHub repo, PyPI project, GHCR, Sigstore keyless, security@ mailbox, domain registrar), records 2FA/recovery practices, and documents a bus-factor mitigation plan. All release-path credentials are short-lived OIDC tokens — there are no long-lived private keys to escrow.
bus_factor UNMET
Evidence:
Known gap. Single-maintainer project. Mitigations (OIDC-only credentials, exhaustive docs, Apache-2.0 license, dead-man's-switch in access_continuity.md §3) reduce custody risk but do not change the headcount. Recruitment is tracked in GOVERNANCE.md and ROADMAP.md.
documentation_roadmap MET
Evidence:
ROADMAP.md describes the project's direction for the next 12 months: v1.x stabilization, planned middleware integrations, the auto-improvement cycle cadence, and Silver/Gold badge milestones. It is updated on every minor release.
documentation_architecture MET
Evidence:
ARCHITECTURE.md (38 KB) documents the major modules, the 6-layer detection pipeline (regex / semantic / decoding / CaMeL / AEP / spec verifier), data flow, and external interfaces. It is reviewed at every minor release.
documentation_security MET
Evidence:
Security requirements and design rationale are documented across: SECURITY.md (reporting + SLAs), docs/assurance_case.md (threat model, adversary model, trust boundaries, secure-design principles), and docs/compliance/ (OWASP LLM Top 10, MITRE ATLAS, NIST AI RMF, CSA STAR, MCP-specific architecture).
documentation_quick_start MET
Evidence:
README.md provides a three-line quick start (`pip install pyaigis; from aigis import Guard; Guard().scan(text)`) and three install paths (pip, Docker, CLI). docs/getting-started.md walks through the first integration end-to-end.
documentation_current MET
Evidence:
Documentation is reviewed and updated on every release. ARCHITECTURE.md, assurance_case.md, access_continuity.md and openssf-best-practices.md each carry a "Last updated" stamp; the release workflow refreshes version badges in README.md. Outdated docs are flagged in PR review.
documentation_achievements MET
Evidence:
The OpenSSF Best Practices badge is embedded in the README.md header alongside CI, CodeQL, Scorecard, license, and PyPI badges. It is rendered at the top of the GitHub project landing page.
accessibility_best_practices N/A
Aigis is a Python library and CLI consumed programmatically — there is no end-user GUI subject to WCAG. Generated HTML reports use semantic markup, sufficient contrast, and keyboard-navigable elements, but the project has no graphical interface for which accessibility best practices would apply.
internationalization MET
Evidence:
The detection rule set ships in four languages (English, Japanese, Korean, Chinese) using NFKC normalization and Unicode confusable handling. UI strings (CLI messages, remediation hints) are short and translation-ready. README.md includes Japanese sections for the JP-leaning user base.
sites_password_security N/A
The project does not run any website that stores user passwords. PyPI and GitHub handle their own authentication; security@ is a forwarder.
achieve_passing MET
Passing tier achieved — see badge on README.md and the project page at bestpractices.dev/projects/12808.
contribution_requirements MET
Evidence: CONTRIBUTING.md
CONTRIBUTING.md documents code style (ruff + ruff format + mypy), test policy (positive + negative cases required), DCO sign-off, PR checklist, and how to add detection patterns or middleware integrations.

2. Change Control（変更管理）

maintenance_or_update MET
Evidence:
SECURITY.md publishes the Supported Versions table (1.0.x — supported; 0.x — end-of-life as of 2026-05-07). Releases follow Semantic Versioning; CHANGELOG.md records every minor and patch release with upgrade notes. Users on unsupported versions are pointed to `pip install --upgrade pyaigis` or `docker pull ghcr.io/killertcell428/aigis:latest`.

3. Reporting（報告）

report_tracker MET
GitHub Issues is the public bug tracker (github.com/killertcell428/aigis/issues). Issue templates live under .github/ISSUE_TEMPLATE/.
vulnerability_report_credit N/A
No external vulnerabilities have been reported and resolved in the past 12 months — the project has only published Dependabot-driven dependency bumps and no third-party CVEs against Aigis itself. SECURITY.md commits to crediting reporters in the advisory + CHANGELOG when this becomes applicable.
vulnerability_response_process MET
Evidence: SECURITY.md
SECURITY.md documents the full coordinated-disclosure process: dual intake channels (GitHub Private Security Advisory and security@killertcell428.dev), SLA table (≤72 h acknowledgment, ≤7 d assessment, ≤60 d fix for high/critical, ≤90 d disclosure), scope, and out-of-scope items.

4. Quality（品質）

coding_standards MET
Evidence: CONTRIBUTING.md "Code Style"; pyproject.toml `[tool.ruff]`, `[tool.mypy]` sections
CONTRIBUTING.md "Code Style" section names ruff (lint + format) and mypy (types) as the project's coding standards. Configuration lives in pyproject.toml under `[tool.ruff]` and `[tool.mypy]`.
coding_standards_enforced MET
Evidence: .github/workflows/ci.yml — ruff + mypy gate
The CI workflow runs `ruff check` and `ruff format --check` on every push and PR. Failures block merge. Pre-commit hooks (.pre-commit-hooks.yaml) offer the same checks locally.
build_repeatable MET
Pure-Python wheel built via `python -m build` from pyproject.toml. uv.lock pins all development dependencies. The release workflow on a fresh Ubuntu runner produces byte-identical wheels for the same git SHA (verified by Sigstore build provenance attestation, see release.yml).
build_standard_variables N/A
Python package build via PEP 517 / `python -m build`; no Makefile-style variables to standardize.
build_preserve_debug N/A
Pure Python — no compiled artifacts that strip debug symbols.
build_non_recursive N/A
Build orchestration is `python -m build` (PEP 517); no recursive make.
installation_common MET
Evidence: README.md "Quick Start"; pyproject.toml
Standard install: `pip install pyaigis`. Uninstall: `pip uninstall pyaigis`. Container: `docker pull ghcr.io/killertcell428/aigis`. All three are documented in README.md "Quick Start". The package follows PEP 621 metadata in pyproject.toml.
installation_standard_variables N/A
Installed via pip into the active Python environment; respects standard `--prefix` / `--user` / venv conventions. No bespoke install variables.
installation_development_quick MET
Evidence: CONTRIBUTING.md "Quick Start for Contributors"
CONTRIBUTING.md "Quick Start for Contributors" provides a four-step setup (fork → clone → `pip install -e '.[dev]'` → `pytest`). The Makefile target `make dev` wraps this for convenience.
external_dependencies MET
Evidence: pyproject.toml, uv.lock
The runtime core has zero external dependencies (Python stdlib only). Optional integrations are declared under `[project.optional-dependencies]` in pyproject.toml (e.g., `pip install pyaigis[anthropic]`). Dev dependencies and their full transitive closure are pinned in uv.lock.
dependency_monitoring MET
Evidence: .github/dependabot.yml; scorecard.yml
Dependabot watches `pip` and `github-actions` ecosystems weekly (.github/dependabot.yml). OpenSSF Scorecard runs weekly via .github/workflows/scorecard.yml and surfaces vulnerable-dependency findings. CodeQL covers Python code paths. Recent example: urllib3 2.7.0 and postcss 8.5.14 bumps (commit b940d3f).
updateable_reused_components MET
All third-party Python packages are installed unmodified via pip from PyPI. No vendored forks. Version constraints in pyproject.toml allow upgrades within compatible ranges; Dependabot opens PRs for security and version updates.
interfaces_current MET
Codebase targets Python 3.11+ — uses current stdlib APIs only. CI matrix runs on 3.11 and 3.12. No use of `imp`, `distutils`, or other deprecated modules; mypy + ruff `UP` ruleset catch deprecated patterns at PR time.
automated_integration_testing MET
Evidence: .github/workflows/ci.yml
CI runs on every push and PR with `ruff check` + `pytest tests/` across Ubuntu × Python 3.11/3.12, plus Windows + macOS smoke runs. 940+ tests, integration-style end-to-end runs included.
regression_tests_added50 PARTIAL
Every patch release that closes a bug is accompanied by a regression test (see `tests/regression_*` and CHANGELOG.md fix entries). Internal review of the last 6 months (cycles 1-8 of the auto-improvement loop) shows ≥ 80% of merged fix PRs ship a regression test. A scripted audit of the bug-fix → test ratio is being added.
test_statement_coverage80 UNMET
Evidence: ci.yml — `--cov-fail-under=68` current floor
Known gap. Current floor enforced at 68% (actual ~69%). Ratchet plan documented in openssf-best-practices.md §Action Items: bump floor by ~5% per minor release until 80%. Untested modules to target: `aigis/safety/*` (240 LOC), `aigis/weekly_report.py` (264 LOC), `aigis/redteam.py` (27%), `aigis/spec_lang/parser.py` (51%).
test_policy_mandated MET
Evidence: CONTRIBUTING.md — PR Checklist
CONTRIBUTING.md "PR Checklist" requires "Tests pass" and "New patterns have both positive and negative tests" as merge prerequisites. CI enforces `pytest` and the coverage floor; PR review enforces the test-for-every-fix rule.
tests_documented_added MET
Already met at Passing tier — see CONTRIBUTING.md "Writing Tests" with worked positive + negative examples.
warnings_strict MET
Already met at Passing tier — ruff runs with strict rule selection (E, F, W, I, B, UP, RUF) and `mypy --strict` is enabled for `aigis/` core in pyproject.toml.

5. Security（セキュリティ）

implement_secure_design MET
Evidence: docs/assurance_case.md §5
docs/assurance_case.md §5 explicitly maps the project's design to the classical secure-design principles: economy of mechanism (stdlib-only core), fail-safe defaults (`Guard(strict=True)`), complete mediation (all I/O flows through `scan*` entry points), open design, separation of privilege (CaMeL control/data flow split), least privilege (capability tokens), least common mechanism (in-process, stateless), psychological acceptability (3-line API), defense in depth (6 layers), work factor (multilingual × encoded × semantic), and compromise recording (activity stream).
crypto_weaknesses MET
Already met at Passing tier — SHA-256 via `hashlib`, PyJWT with an explicit algorithm allowlist (no `alg: none` accepted). No bespoke crypto in core.
crypto_algorithm_agility N/A
Aigis core does not implement cryptographic primitives; it consumes Python `hashlib` and PyJWT which both expose algorithm selection. No agility migration is needed at the project layer.
crypto_credential_agility N/A
No long-lived credentials managed by the library — see access_continuity.md for the release-path credentials (all OIDC, no embedded private keys).
crypto_used_network N/A
Core ships no network code. The library is in-process. Distribution (PyPI, GHCR) uses HTTPS handled by the underlying package managers.
crypto_tls12 N/A
No network endpoints exposed by the library. TLS is delegated to PyPI / GHCR / pip / docker.
crypto_certificate_verification N/A
No outbound network calls in the core. Optional middleware (e.g., Anthropic SDK integration) uses the host SDK's TLS verification, which is on by default.
crypto_verification_private N/A
No private key material handled by the library.
signed_releases MET
Evidence: release.yml — `actions/attest-build-provenance@v2`
Release workflow generates SLSA build provenance attestations (Sigstore, keyless OIDC) for every wheel and sdist via `actions/attest-build-provenance@v2`. Attestations are queryable at github.com/killertcell428/aigis/attestations. PyPI uploads use Trusted Publishing (OIDC) — no long-lived API token is stored.
version_tags_signed PARTIAL
Release artifacts carry Sigstore attestations. Git tag signing (`git tag -s`) is encouraged for maintainers but not yet enforced via branch-protection rules. Plan: enable "Require signed commits/tags" on `master` after migrating to a hardware-key-backed signing key.
input_validation MET
The library's core function *is* input validation against an explicit allowlist of detection patterns. Public APIs (`Guard.scan`, `scan_output`, `scan_mcp_tool`) accept typed inputs (`str`, `dict`) and reject malformed structures with `TypeError`/`ValueError` before reaching the detection pipeline.
hardening MET
As a library, Aigis inherits the host process's hardening. The published Docker image (Dockerfile) runs as a non-root user, sets `PYTHONHASHSEED=random`, and uses a slim base. CI runs with least-privilege `permissions:` blocks per job; release.yml uses `id-token: write` only in the publish jobs.
assurance_case MET
Evidence: docs/assurance_case.md
docs/assurance_case.md documents the claim, adversary model (A1–A7), trust boundaries (T1–T3), top-10 threats with mitigation mapping, secure-design principle realization, operating assumptions, evidence index, and review cadence.

6. Analysis（分析）

static_analysis_common_vulnerabilities MET
CodeQL runs on push and PR (.github/workflows/codeql.yml) with security-and-quality queries for Python. OpenSSF Scorecard runs weekly. ruff + mypy run on every PR via ci.yml.
dynamic_analysis_unsafe N/A
Pure Python (memory-safe). No C/C++/Rust unsafe code paths to analyze.

7. 残存ギャップと対応計画

Criterion状態計画目標
bus_factor UNMET 共同メンテナ募集 — GOVERNANCE.md「Becoming a Maintainer」セクションで継続募集。3 PR以上 + 90日アクティブ後に Maintainer 昇格。 v1.2.0 リリース時
test_statement_coverage80 UNMET 現状 69% → 80%。aigis/safety/*, weekly_report.py, redteam.py, spec_lang/parser.py に重点的にテスト追加。--cov-fail-under をマイナーリリースごとに +5%。 v1.3.0 リリース時
regression_tests_added50 PARTIAL 過去6ヶ月のbug-fix PRの50%以上に対応する回帰テスト存在を CI で監査する script を追加。 次回マイナーリリース
version_tags_signed PARTIAL ハードウェアキーで git tag -s。master ブランチに「Require signed tags」ルール追加。 次回パッチリリース

Appendix — 投入手順

  1. このページを bestpractices.dev/ja/projects/12808/silver と並べて開く。
  2. 各項目の justification テキストエリアに、上記の青枠（.justification）の本文をコピー&ペースト。
  3. 該当する Met / Unmet / N/A ラジオボタンを選択。
  4. Evidence URL 欄には https://github.com/killertcell428/aigis/blob/master/<path> 形式の絶対URLを記入。
  5. 残存ギャップ（bus_factor, test_statement_coverage80）は Unmet のまま、justification 欄に「計画」を記入。Silver 完全達成にはこれら2項目を解消する必要があります。