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.2 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@v7.2.0
  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 Jul 13, 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 Jul 13, 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.2.tar.gz (422.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.2-py3-none-any.whl (560.9 kB view details)

Uploaded Python 3

File details

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

File metadata

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

File hashes

Hashes for oss_policy_kit-10.0.2.tar.gz
Algorithm Hash digest
SHA256 8a75cd4c8c205c5f7fc6797357b2483500f1219a5d9e1ac8ce157508f7112531
MD5 ebaba1c77b9cb4de75d4cb36e93c5919
BLAKE2b-256 027c9b1b8d431a39787a1c000bf2c13c0a152a433fac67fa99999e1811963073

See more details on using hashes here.

Provenance

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

File metadata

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

File hashes

Hashes for oss_policy_kit-10.0.2-py3-none-any.whl
Algorithm Hash digest
SHA256 7d884147fd40edf649e1b9bf6fbf1b9074e6d7b4ca06b012fbea9309120d9c3a
MD5 e00045a2c4bd7b147c62f8a5784d1f08
BLAKE2b-256 93ece92d66a721a55100f52f11eb4c1678f886276d5b07b5f398fc8cbeb09202

See more details on using hashes here.

Provenance

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

10.0.5

2 files

10.0.4

2 files

10.0.3

2 files

This release

10.0.2 This release

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