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.5 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.

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.
  • 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.5 # 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
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

Contributing and Security

License

Apache-2.0. See LICENSE and NOTICE.

Project links

Data verified by PyPI on Aug 5, 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 Aug 5, 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.5.tar.gz (424.4 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.5-py3-none-any.whl (561.1 kB view details)

Uploaded Python 3

File details

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

File metadata

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

File hashes

Hashes for oss_policy_kit-10.0.5.tar.gz
Algorithm Hash digest
SHA256 816c1e357570af101571a0ab09f115cb4743f995867c48650245959a9dfab043
MD5 789a57a42ee1e19f898de768f5f8bf49
BLAKE2b-256 95014806656e712a3dad2836fcb66357a917eaa9f7352047daa7a7336ea9a725

See more details on using hashes here.

Provenance

The following attestation bundles were made for oss_policy_kit-10.0.5.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.5-py3-none-any.whl.

File metadata

  • Download URL: oss_policy_kit-10.0.5-py3-none-any.whl
  • Upload date:
  • Size: 561.1 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.14

File hashes

Hashes for oss_policy_kit-10.0.5-py3-none-any.whl
Algorithm Hash digest
SHA256 6676b543027e586249c6be23ec3643bea0996792015b9921eff927750a218c81
MD5 210bfa4befd5447ff985f4e643705133
BLAKE2b-256 60d3d6e13292eca6928ba62613c09986bf86e1fb8f3f430cedf3cb1431ff9b36

See more details on using hashes here.

Provenance

The following attestation bundles were made for oss_policy_kit-10.0.5-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

10.0.20

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

This release

10.0.5 This release

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