AppSec Rules Pack

A versioned AppSec rules pack and the validator that keeps it honest. Each rule states what to review, what evidence proves it, how to fix it, and how long an exception may last, with mappings to OWASP ASVS 5.0, the OWASP API Security Top 10, OWASP Top 10:2025, CWE, and NIST SSDF. The appsec-rules CLI validates packs against a JSON Schema contract and semantic checks, so a pack can serve as a CI quality gate and as review evidence.

The demo is real CLI output. Recreate it from a source checkout with python docs/assets/record-cli-demo.py.

Contents

• Scope
• Quick start
• Installation
• Verify a release
• CLI reference
• Writing a rules pack
• Use it in CI
• Optional executable Semgrep rules
• Project layout
• Documentation
• Contributing, security, and license

Scope

The baseline covers authentication, authorization, input validation, injection and XSS, SSRF, secrets, file handling, logging, dependency risk, configuration, session hardening, CSRF, webhook integrity, excessive data exposure, mass assignment, open redirect, and rate limiting. It contains no product names, tenant identifiers, customer data, secrets, or environment-specific configuration.

Mapping coverage of the baseline: ASVS 5.0, API Top 10 2023, CWE, and NIST SSDF on 19 of 19 rules; the optional OWASP Top 10:2025 field on 18 of 19.

Quick start

pip install "appsec-rules-pack==0.4.1"
curl -LO https://github.com/lucashgrifoni/AppSec-Rules-Pack/releases/download/v0.4.1/appsec-baseline.yaml
appsec-rules validate appsec-baseline.yaml --require-examples --fail-on-warnings

Expected output: Validation passed: 1 file, 19 rules, 0 errors, 0 warnings.

Installation

pip install appsec-rules-pack

This installs the appsec-rules console script and requires Python 3.12 or newer. Pin a reviewed version, such as appsec-rules-pack==0.4.1, when the CLI runs as a quality gate.

The distribution contains the validator, the CLI, and the JSON Schema. It does not contain a rules pack. Take the baseline from the assets of the release you pin, copy rules/appsec-baseline.yaml, or write your own pack.

To work from source:

python -m venv .venv
.venv/bin/python -m pip install -e ".[dev]"     # Windows: .venv\Scripts\python

Verify a release

Every release is built and published by publish-pypi.yml through PyPI Trusted Publishing, with no long-lived token. Each GitHub Release carries the wheel, the sdist, a CycloneDX SBOM (sbom.cdx.json), the baseline pack, and, from v0.4.0, the signed provenance bundle (appsec-rules-pack-<tag>.intoto.jsonl). The wheel, sdist, SBOM, and baseline pack carry a SLSA build-provenance attestation.

Verify a downloaded asset with a current GitHub CLI:

gh attestation verify appsec-baseline.yaml \
  --repo lucashgrifoni/AppSec-Rules-Pack \
  --signer-workflow lucashgrifoni/AppSec-Rules-Pack/.github/workflows/publish-pypi.yml \
  --source-ref refs/tags/v0.4.1

Or offline, against the bundle attached to the release:

gh attestation verify appsec-baseline.yaml \
  --repo lucashgrifoni/AppSec-Rules-Pack \
  --bundle appsec-rules-pack-v0.4.1.intoto.jsonl

The same commands work for the wheel, the sdist, and sbom.cdx.json. A passing check proves the artifact came from this repository's release workflow at that tag. It does not prove the rule guidance is complete or that an application is secure. Treat a failed or unavailable check as unverified provenance. ADR-0003 explains the release design.

CLI reference

validate options:

The JSON report has a summary object (files, rules, errors, warnings, ok) and a files array of per-file issues (level, path, message). Validation exits 0 on a passing pack, 1 on a failing one, and 2 on a usage error such as a missing path.

The export and coverage commands only derive metadata; they do not validate first. Run validate --require-examples --fail-on-warnings as the gate. From a source checkout, python -m appsec_rules_pack works in place of appsec-rules.

Writing a rules pack

A pack is a pack block plus one or more rules. This minimal pack is complete and valid: copy it, validate it, and grow it. Every field shown is required. The full contract is appsec-rule.schema.json, and the 19 rules in rules/appsec-baseline.yaml are worked examples.

pack:
  id: my-pack
  name: My Rules Pack
  version: 0.1.0
  mode: advisory
  owner: appsec
  description: A minimal rules pack to start from.

rules:
  - id: APPSEC-EXAMPLE-001
    title: Require controlled error handling
    description: Verify that invalid user input returns controlled errors without stack traces.
    severity: medium
    category: configuration
    status: enabled
    enforcement: advisory
    targets:
      - api
    mappings:
      owasp_asvs:
        - V14.4
      owasp_api_top_10_2023:
        - API8:2023
      cwe:
        - CWE-209
      nist_ssdf:
        - PW.7
    evidence:
      required:
        - Error handling path returns a documented response shape.
      signals:
        - Negative tests assert controlled error messages for invalid input.
    match:
      type: review
      includes:
        - API handlers that process untrusted input.
      excludes:
        - Local developer-only scripts that are not shipped.
    remediation:
      guidance: Replace raw exception output with a controlled error contract.
      validation:
        - Run negative tests for invalid input and malformed requests.
    exceptions:
      allowed: true
      max_days: 30
      required_fields:
        - owner
        - justification
        - expires_at

Shapes that are easy to get wrong: evidence and match are objects, not lists; remediation needs guidance; required_fields accepts only owner, justification, expires_at, compensating_control, and validation_plan.

Rules are advisory by default. Each one carries a stable ID and severity, a target surface and category, framework mappings, expected evidence and review signals, match guidance, remediation and validation steps, exception requirements, a lifecycle status (deprecated rules carry a deprecation block), and a compliant and a violating example. CONTRIBUTING.md describes the severity model and the topic-based mapping convention.

Use it in CI

• examples/README.md has a GitHub Actions job that installs a pinned release and runs the strict JSON gate.
• examples/validation_gate.py is a stdlib-only gate for any other CI system. It passes only when the CLI exits 0 and the report says ok: true.
• .github/workflows/policy-gate.yml is this repository's reference gate that consumes the JSON report.

Optional executable Semgrep rules

exports/semgrep-rules/ holds two hand-maintained, tested Semgrep rules, kept separate from the validator (ADR-0005):

The other 17 baseline rules have no executable detection, and these two cover only their documented source and sink combinations. The layer README lists the known false positives and false negatives. Run the fixture suite with a separately installed engine:

python -m pip install "semgrep==1.179.0"
semgrep --test --strict --metrics=off --config exports/semgrep-rules/rules exports/semgrep-rules/tests

The appsec-rules CLI never invokes Semgrep, and export semgrep still emits only the metadata scaffold.

Project layout

.github/            CI, security, policy-gate, Scorecard, Pages, and release workflows
docs/adr/           Architecture decision records
docs/assets/        CLI demo and social preview
examples/           CI integration examples
exports/            Derived artifacts and the optional executable Semgrep rules
rules/              The baseline rules pack
site/               Source of the project landing page
src/appsec_rules_pack/
                    Validator, CLI, exporters, and the JSON Schema
tests/              Test suite and pass, fail, and warning fixtures

Documentation

Contributing, security, and license

Contributions are welcome. Read CONTRIBUTING.md for rule authoring principles, the severity and exception models, and the required checks:

python -m ruff check .
python -m pytest --cov=appsec_rules_pack --cov-report=term-missing
python -m appsec_rules_pack validate rules --require-examples --fail-on-warnings
python -m build

Participation follows the Code of Conduct. Report vulnerabilities privately as described in SECURITY.md; do not open a public issue.

Licensed under the Apache License 2.0.