OSS Security Policy as Code Starter Kit

Pass/fail security policy gates for OSS repositories, with explicit assurance grading and framework mappings.

CI Security CI PyPI Python License

At a Glance

oss-policy-kit evaluates a local repository clone plus optional evidence files, then emits Markdown, JSON, and optional SARIF reports for humans and CI gates.

Current release Bundled profiles Controls CLI commands Python
v10.0.20 56 222 23 3.12+

Use it when you need a local-first gate that combines repository governance, CI/CD hardening, release posture, scanner evidence, waivers, and framework-oriented reporting. It is not a vulnerability scanner, certification engine, or legal compliance guarantee.

Status: maintenance. v10.0.0 completed the planned end-state. Releases since have been hardening and correctness work, not new surface. Issues and questions are still answered.

Every Verdict Carries Its Assurance

Most tools give a verdict. This one also records how that verdict was reached, so a wrong result can be argued with evidence instead of taken on faith.

Assurance How the verdict was established What it is worth
deterministic Read directly from the clone Highest confidence — the file either is or is not there
signal Heuristic inference from what is visible Corroborating only. A signal never elevates a grade on its own
evidence-backed Rests on API-backed evidence you supply Exactly as strong as the evidence behind it

A control that fires wrongly is worse than one that does not exist. False-positive reports are welcome, and the assurance label is what makes that argument precise.

Quickstart

python -m pip install oss-policy-kit
python -m oss_policy_kit init --target . --with-evidence --with-workflow
python -m oss_policy_kit evaluate --target . --profile github-level-1 --fail-on fail

The evaluation writes:

  • evaluation-report.md for review.
  • evaluation-report.json for automation.
  • evaluation-report.sarif when --sarif-output is set.

First-time tutorial: docs/tutorial-first-pr-gate.md. Compact CLI reference: docs/quickstart-15-min.md.

What It Does

  • Evaluates bundled policy profiles against a repository clone.
  • Uses optional evidence under .oss-policy-kit/evidence/ for platform-only facts.
  • Composes signals from local files, workflows, SARIF/JSON scanner outputs, waivers, and release evidence.
  • Correlates composed scanner findings into one deduplicated, ranked findings/1.0 artifact (correlate-findings).
  • Labels controls by assurance type: deterministic, signal, or evidence-backed — see above.
  • Supports Markdown, JSON report contracts, and optional SARIF for code-scanning workflows.
  • Keeps waivers visible with owner, reason, and expiry metadata.

What It Does Not Do

  • It does not certify CRA, SLSA, OSPS, SSDF, or AI Act compliance.
  • It does not replace SAST, SCA, secrets scanning, threat modeling, secure code review, pentesting, or live platform review.
  • It does not prove branch protection, rulesets, MFA, cloud posture, or registry settings unless you provide API-backed evidence.
  • It does not claim SLSA Build L3. The current trust model is documented in docs/supply-chain-verification.md.

Core Capabilities

Area Included
Repository governance LICENSE, SECURITY, CONTRIBUTING, CODEOWNERS, branch protection evidence, release hygiene
CI/CD posture GitHub Actions, Azure Pipelines, AWS CodeBuild/CodePipeline, GitLab CI signals
Release hardening OIDC publishing, provenance evidence, artifact verification, source-built container flow
Scanner composition SARIF/JSON ingestion for tools such as zizmor, OSV-Scanner, Gitleaks, Scorecard, and Semgrep
Finding correlation correlate-findings: one normalized, deduplicated, KEV/EPSS-ranked findings/1.0 view across all composed scanners (stateless, single run)
Framework mapping OSPS, NIST SSDF, SLSA, S2C2F, OWASP CI/CD, EU CRA, EU AI Act readiness signals
AI and agent security AI agent source-side checks, MCP server security, OWASP Agentic ASI mapping
Exception handling Waiver registry with reason, owner, scope, and expiry

Profiles

List bundled profiles:

python -m oss_policy_kit profiles

Common starting points:

Profile Use when
github-level-1 First GitHub repository gate
github-level-2 Stricter GitHub governance and CI/CD posture
oss-publish-readiness-1 Release/publish readiness for OSS packages
appsec-sast-sca-1 Compose SAST/SCA/secrets scanner evidence
osps-baseline-2026-1 OpenSSF OSPS Baseline 2026-oriented review
cra-eu-conformance-evidence-1 EU CRA Article 13/14 conformance-evidence signals
ai-agent-baseline-1 Source-side checks for AI agent repositories
appsec-mcp-server-1 MCP server security readiness

Full profile guide: docs/profiles/overview.md.

GitHub Action

- uses: lucashgrifoni/OSS-Security-Policy-as-Code-Starter-Kit@v10.0.20 # x-release-please-version
  with:
    profile: github-level-1
    fail-on: fail

Action reference: docs/github-action.md. Starter workflows live under templates/workflows/.

Reports and Contracts

evaluate writes reports/2.0 JSON — the only report contract since v9.0.0 (ADR-043). The legacy pre-2.0 contracts (0.1/0.2/0.3/1.0) were removed; --report-json-contract accepts only 2.0 (any other value is a clean exit-2 error, never a silent fallback). Contracts and migration:

Exit codes:

Code Meaning
0 Success; configured fail threshold was not violated
1 Evaluation completed and the fail threshold was violated
2 Usage, validation, or load error
3 Unexpected internal error

Supply Chain Verification

PyPI publication uses Trusted Publishing and registry attestations. Release artifacts also use GitHub Artifact Attestations. Container images are built from the checked-out release source tree, signed with cosign keyless, and attested.

Verification commands and limits are in docs/supply-chain-verification.md.

Documentation Map

Topic Link
Project wiki Wiki
Documentation index docs/README.md
Architecture docs/architecture.md
CLI reference docs/cli-reference.md
Results guide docs/results-guide.md
Framework alignment docs/framework-alignment.md
Positioning and limits docs/positioning.md
EU CRA readiness docs/cra-readiness.md
EU AI Act readiness docs/eu-ai-act-readiness.md
MCP server security docs/mcp-server-security.md
Release readiness docs/release-readiness.md
Changelog CHANGELOG.md

Repository Layout

Path Purpose
src/oss_policy_kit/ Python package, CLI, evaluators, parsers, reporting
src/oss_policy_kit/data/ Bundled controls, profiles, and schemas
templates/ Starter workflows, waivers, docs, and ruleset examples
examples/ Hardened and vulnerable example repositories
tests/ Unit, application, integration, infrastructure, and property tests
docs/ User docs, architecture, mappings, ADRs, and release notes
reports/ Published JSON Schemas for the report and evidence contracts
waivers/ Waiver registry: the live file plus a documented example
pipelines/ Azure Pipelines starter definition
scripts/ Maintenance and generator scripts, including the public-hygiene check
gitpage/ Source and prebuilt bundle for the GitHub Pages site
.github/ Workflows, Dependabot config, and issue/PR templates

Only the oss_policy_kit package ships in the wheel. Everything else — templates, examples, schemas, pipelines — is consumed from this repository, so pin a tag when you copy from it.

Contributing and Security

License

Apache-2.0. See LICENSE and NOTICE.

Project links

Data verified by PyPI on Sep 9, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (10.0.23)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for lucashgrifoni from gravatar.com lucashgrifoni

Credits

Author: Lucas Henrique Grifoni

GitHub Statistics

Data verified by PyPI on Sep 9, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

Apache-2.0
View SPDX License List

Requires

Python >=3.12

Provides Extra

github gitlab azure aws iac all dev

Tags

open-source security policy github-actions devsecops osps

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

oss_policy_kit-10.0.20.tar.gz (562.1 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

oss_policy_kit-10.0.20-py3-none-any.whl (702.8 kB view details)

Uploaded Python 3

File details

Details for the file oss_policy_kit-10.0.20.tar.gz.

File metadata

  • Download URL: oss_policy_kit-10.0.20.tar.gz
  • Upload date:
  • Size: 562.1 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for oss_policy_kit-10.0.20.tar.gz
Algorithm Hash digest
SHA256 c7b2008dac623fdf365b68d9611351f7e1c644eb884e0e5eaea2f4cfa50e47fd
MD5 31219fb60236280c7563a13ab94e1f59
BLAKE2b-256 e2055ca2e38d2fd6c6b9a9033b732f9a424b9cab756792494bc75bef93b3a977

See more details on using hashes here.

Provenance

The following attestation bundles were made for oss_policy_kit-10.0.20.tar.gz:

Publisher: publish-pypi.yml on lucashgrifoni/OSS-Security-Policy-as-Code-Starter-Kit

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file oss_policy_kit-10.0.20-py3-none-any.whl.

File metadata

File hashes

Hashes for oss_policy_kit-10.0.20-py3-none-any.whl
Algorithm Hash digest
SHA256 114507a788dbe0273d45cd32eb6b40a51bb9ecb70f00fd31f6021d1a55351da6
MD5 97c992b47205760ead3487773f936252
BLAKE2b-256 e543e1ad7075fc28c068063a984ecb7b9ff734372789273885dc4a45af155ccf

See more details on using hashes here.

Provenance

The following attestation bundles were made for oss_policy_kit-10.0.20-py3-none-any.whl:

Publisher: publish-pypi.yml on lucashgrifoni/OSS-Security-Policy-as-Code-Starter-Kit

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

10.0.23

2 files

10.0.22

2 files

10.0.21

2 files

This release

10.0.20 This release

2 files

10.0.19

2 files

10.0.18

2 files

10.0.17

2 files

10.0.16

2 files

10.0.15

2 files

10.0.14

2 files

10.0.13

2 files

10.0.12

2 files

10.0.11

2 files

10.0.10

2 files

10.0.9

2 files

10.0.8

2 files

10.0.7

2 files

10.0.6

2 files

10.0.5

2 files

10.0.4

2 files

10.0.3

2 files

10.0.2

2 files

10.0.1

2 files

10.0.0

2 files

9.0.3

2 files

9.0.2

2 files

9.0.1

2 files

9.0.0

2 files

8.1.0

2 files

8.0.0

2 files

7.3.0

2 files

7.2.0

2 files

7.1.0

2 files

7.0.1

2 files

7.0.0

2 files

6.7.0

2 files

6.6.0

2 files

6.5.1

2 files

6.5.0

2 files

6.4.0

2 files

6.3.0

2 files

6.2.0

2 files

6.1.0

2 files

6.0.1

2 files

6.0.0

2 files

5.9.1

2 files

5.9.0

2 files

5.8.1

2 files

5.8.0

2 files

5.7.0

2 files

5.6.0

2 files

Pre-release

5.6.0.dev0

2 files

5.5.0

2 files

5.4.0

2 files

5.1.0

2 files

5.0.0

2 files

4.0.4

2 files

4.0.3

2 files

4.0.2

2 files

4.0.1

2 files

3.0.0

2 files

2.0.1

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page