appsec-rules-pack 0.2.0__tar.gz → 0.3.0__tar.gz

{appsec_rules_pack-0.2.0 → appsec_rules_pack-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: appsec-rules-pack
-Version: 0.2.0
+Version: 0.3.0
 Summary: Generic AppSec policy-as-code rules pack and validator.
 Author: Lucas Henrique Grifoni
 License-Expression: Apache-2.0
@@ -38,6 +38,7 @@ Dynamic: license-file
 [![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/lucashgrifoni/AppSec-Rules-Pack/badge)](https://scorecard.dev/viewer/?uri=github.com/lucashgrifoni/AppSec-Rules-Pack)
 [![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
 [![Python](https://img.shields.io/badge/python-3.12%2B-blue.svg)](pyproject.toml)
+[![PyPI](https://img.shields.io/pypi/v/appsec-rules-pack.svg)](https://pypi.org/project/appsec-rules-pack/)
 
 Reusable AppSec policy-as-code rules for secure application review, CI quality gates,
 and manual evidence collection.
@@ -69,9 +70,11 @@ configuration.
   enum/type/additionalProperties failures, duplicate rule IDs, cross-file
   duplicate IDs, exception-window warnings, exception-policy contradictions,
   malformed framework mapping IDs, and sensitive-value detection.
-- A 90% coverage gate plus a hardened CI/CD surface: a build/lint/test workflow,
-  a security pipeline (Semgrep, CodeQL, Bandit, Trivy, KICS, pip-audit, Gitleaks,
-  Dependency Review, actionlint), and OpenSSF Scorecard analysis.
+- A 95% coverage gate plus a hardened CI/CD surface: a build/lint/test workflow (with
+  separate jobs running the suite on Ubuntu and Windows, and on Python 3.13), a security
+  pipeline (Semgrep, CodeQL, Bandit, Trivy, KICS, pip-audit, Gitleaks, Dependency Review,
+  actionlint), and OpenSSF Scorecard analysis. The build/lint/test, cross-platform, and
+  security jobs are required status checks on `master`.
 - Contribution guidance for safe rule additions, a code of conduct, and issue/PR
   templates.
 - A CI integration template in `examples/`.
@@ -87,6 +90,8 @@ configuration.
 |   |   `-- rule_proposal.md
 |   |-- workflows/
 |   |   |-- ci.yml
+|   |   |-- policy-gate.yml
+|   |   |-- publish-pypi.yml
 |   |   |-- scorecard.yml
 |   |   `-- security-ci-cd.yml
 |   |-- CODEOWNERS
@@ -94,6 +99,12 @@ configuration.
 |   `-- dependabot.yml
 |-- examples/
 |   `-- README.md
+|-- exports/
+|   |-- appsec-baseline.index.json
+|   |-- sarif/
+|   |   `-- appsec-baseline.sarif.json
+|   `-- semgrep/
+|       `-- appsec-baseline.semgrep.yaml
 |-- rules/
 |   `-- appsec-baseline.yaml
 |-- src/
@@ -101,7 +112,11 @@ configuration.
 |       |-- __init__.py
 |       |-- __main__.py
 |       |-- cli.py
+|       |-- exporter.py
 |       |-- loader.py
+|       |-- reporter.py
+|       |-- sarif_export.py
+|       |-- semgrep_scaffold.py
 |       |-- validator.py
 |       `-- schemas/
 |           `-- appsec-rule.schema.json
@@ -112,12 +127,11 @@ configuration.
 |   |   |-- fail/
 |   |   |-- pass/
 |   |   `-- warn/
-|   |-- test_edge_cases.py
-|   |-- test_examples.py
-|   |-- test_loader.py
-|   |-- test_packaging.py
-|   |-- test_validator.py
-|   `-- test_validator_paths.py
+|   |-- helpers.py        # shared subprocess helper for tests that shell out
+|   `-- test_*.py         # one module per validated behaviour
+|-- .gitattributes
+|-- .gitignore
+|-- .gitleaks.toml
 |-- CHANGELOG.md
 |-- CODE_OF_CONDUCT.md
 |-- CONTRIBUTING.md
@@ -130,7 +144,31 @@ configuration.
 `-- pyproject.toml
 ```
 
-## Setup
+## Installation
+
+Install the published package from PyPI:
+
+```bash
+pip install appsec-rules-pack
+```
+
+This installs the `appsec-rules` console script. Pin to a reviewed version
+(for example `appsec-rules-pack==0.3.0`) when using it in a CI quality gate.
+
+**What the distribution contains:** the validator, the CLI, and the JSON Schema. It does
+not ship a rules pack — the CLI validates whatever path you point it at.
+
+To get the baseline pack of 19 rules, either take the version-pinned copy attached to each
+GitHub Release:
+
+```bash
+curl -LO https://github.com/lucashgrifoni/AppSec-Rules-Pack/releases/download/v0.3.0/appsec-baseline.yaml
+```
+
+or copy [`rules/appsec-baseline.yaml`](rules/appsec-baseline.yaml) from this repository.
+You can also write your own pack from the example below.
+
+### From source (development)
 
 ```powershell
 python -m venv .venv
@@ -147,8 +185,78 @@ python -m venv .venv
 If the dependencies already exist in the active Python environment, the validator can
 also be run directly with `PYTHONPATH=src`.
 
+## Your First Rules Pack
+
+A pack is a `pack` block plus one or more `rules`. This is a complete, valid minimal pack —
+copy it, run `appsec-rules validate` on it, then grow it. Every field shown is required; the
+full contract is in
+[`appsec-rule.schema.json`](src/appsec_rules_pack/schemas/appsec-rule.schema.json), and the
+19 baseline rules in [`rules/appsec-baseline.yaml`](rules/appsec-baseline.yaml) are worked
+examples.
+
+<!-- readme-example:minimal-pack (validated by tests/test_readme_example.py) -->
+
+```yaml
+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
+```
+
+Note the shapes that are easy to guess wrong: `evidence` and `match` are objects (not
+lists), `remediation` needs `guidance`, and `required_fields` accepts only `owner`,
+`justification`, `expires_at`, `compensating_control`, and `validation_plan`.
+
 ## Usage
 
+The examples below use `rules/appsec-baseline.yaml`, which exists in **this repository**.
+If you installed from PyPI, point the CLI at your own rules file or directory instead.
+
 Validate the baseline rules pack:
 
 ```bash
@@ -205,9 +313,9 @@ code is non-zero when validation fails, matching the text output.
 
 ## Use It In Your CI
 
-`examples/README.md` contains a GitHub Actions template for installing the pack,
-validating a rules directory, and failing the build on errors (and optionally
-warnings). Pin the template to a reviewed tag or commit before enabling it as a
+`examples/README.md` contains a GitHub Actions template for installing the pack from
+PyPI, validating a rules directory, and failing the build on errors (and optionally
+warnings). Pin the install to a reviewed release version before enabling it as a
 quality gate.
 
 ## Rule Pack Model

{appsec_rules_pack-0.2.0 → appsec_rules_pack-0.3.0}/README.md

@@ -5,6 +5,7 @@
 [![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/lucashgrifoni/AppSec-Rules-Pack/badge)](https://scorecard.dev/viewer/?uri=github.com/lucashgrifoni/AppSec-Rules-Pack)
 [![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
 [![Python](https://img.shields.io/badge/python-3.12%2B-blue.svg)](pyproject.toml)
+[![PyPI](https://img.shields.io/pypi/v/appsec-rules-pack.svg)](https://pypi.org/project/appsec-rules-pack/)
 
 Reusable AppSec policy-as-code rules for secure application review, CI quality gates,
 and manual evidence collection.
@@ -36,9 +37,11 @@ configuration.
   enum/type/additionalProperties failures, duplicate rule IDs, cross-file
   duplicate IDs, exception-window warnings, exception-policy contradictions,
   malformed framework mapping IDs, and sensitive-value detection.
-- A 90% coverage gate plus a hardened CI/CD surface: a build/lint/test workflow,
-  a security pipeline (Semgrep, CodeQL, Bandit, Trivy, KICS, pip-audit, Gitleaks,
-  Dependency Review, actionlint), and OpenSSF Scorecard analysis.
+- A 95% coverage gate plus a hardened CI/CD surface: a build/lint/test workflow (with
+  separate jobs running the suite on Ubuntu and Windows, and on Python 3.13), a security
+  pipeline (Semgrep, CodeQL, Bandit, Trivy, KICS, pip-audit, Gitleaks, Dependency Review,
+  actionlint), and OpenSSF Scorecard analysis. The build/lint/test, cross-platform, and
+  security jobs are required status checks on `master`.
 - Contribution guidance for safe rule additions, a code of conduct, and issue/PR
   templates.
 - A CI integration template in `examples/`.
@@ -54,6 +57,8 @@ configuration.
 |   |   `-- rule_proposal.md
 |   |-- workflows/
 |   |   |-- ci.yml
+|   |   |-- policy-gate.yml
+|   |   |-- publish-pypi.yml
 |   |   |-- scorecard.yml
 |   |   `-- security-ci-cd.yml
 |   |-- CODEOWNERS
@@ -61,6 +66,12 @@ configuration.
 |   `-- dependabot.yml
 |-- examples/
 |   `-- README.md
+|-- exports/
+|   |-- appsec-baseline.index.json
+|   |-- sarif/
+|   |   `-- appsec-baseline.sarif.json
+|   `-- semgrep/
+|       `-- appsec-baseline.semgrep.yaml
 |-- rules/
 |   `-- appsec-baseline.yaml
 |-- src/
@@ -68,7 +79,11 @@ configuration.
 |       |-- __init__.py
 |       |-- __main__.py
 |       |-- cli.py
+|       |-- exporter.py
 |       |-- loader.py
+|       |-- reporter.py
+|       |-- sarif_export.py
+|       |-- semgrep_scaffold.py
 |       |-- validator.py
 |       `-- schemas/
 |           `-- appsec-rule.schema.json
@@ -79,12 +94,11 @@ configuration.
 |   |   |-- fail/
 |   |   |-- pass/
 |   |   `-- warn/
-|   |-- test_edge_cases.py
-|   |-- test_examples.py
-|   |-- test_loader.py
-|   |-- test_packaging.py
-|   |-- test_validator.py
-|   `-- test_validator_paths.py
+|   |-- helpers.py        # shared subprocess helper for tests that shell out
+|   `-- test_*.py         # one module per validated behaviour
+|-- .gitattributes
+|-- .gitignore
+|-- .gitleaks.toml
 |-- CHANGELOG.md
 |-- CODE_OF_CONDUCT.md
 |-- CONTRIBUTING.md
@@ -97,7 +111,31 @@ configuration.
 `-- pyproject.toml
 ```
 
-## Setup
+## Installation
+
+Install the published package from PyPI:
+
+```bash
+pip install appsec-rules-pack
+```
+
+This installs the `appsec-rules` console script. Pin to a reviewed version
+(for example `appsec-rules-pack==0.3.0`) when using it in a CI quality gate.
+
+**What the distribution contains:** the validator, the CLI, and the JSON Schema. It does
+not ship a rules pack — the CLI validates whatever path you point it at.
+
+To get the baseline pack of 19 rules, either take the version-pinned copy attached to each
+GitHub Release:
+
+```bash
+curl -LO https://github.com/lucashgrifoni/AppSec-Rules-Pack/releases/download/v0.3.0/appsec-baseline.yaml
+```
+
+or copy [`rules/appsec-baseline.yaml`](rules/appsec-baseline.yaml) from this repository.
+You can also write your own pack from the example below.
+
+### From source (development)
 
 ```powershell
 python -m venv .venv
@@ -114,8 +152,78 @@ python -m venv .venv
 If the dependencies already exist in the active Python environment, the validator can
 also be run directly with `PYTHONPATH=src`.
 
+## Your First Rules Pack
+
+A pack is a `pack` block plus one or more `rules`. This is a complete, valid minimal pack —
+copy it, run `appsec-rules validate` on it, then grow it. Every field shown is required; the
+full contract is in
+[`appsec-rule.schema.json`](src/appsec_rules_pack/schemas/appsec-rule.schema.json), and the
+19 baseline rules in [`rules/appsec-baseline.yaml`](rules/appsec-baseline.yaml) are worked
+examples.
+
+<!-- readme-example:minimal-pack (validated by tests/test_readme_example.py) -->
+
+```yaml
+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
+```
+
+Note the shapes that are easy to guess wrong: `evidence` and `match` are objects (not
+lists), `remediation` needs `guidance`, and `required_fields` accepts only `owner`,
+`justification`, `expires_at`, `compensating_control`, and `validation_plan`.
+
 ## Usage
 
+The examples below use `rules/appsec-baseline.yaml`, which exists in **this repository**.
+If you installed from PyPI, point the CLI at your own rules file or directory instead.
+
 Validate the baseline rules pack:
 
 ```bash
@@ -172,9 +280,9 @@ code is non-zero when validation fails, matching the text output.
 
 ## Use It In Your CI
 
-`examples/README.md` contains a GitHub Actions template for installing the pack,
-validating a rules directory, and failing the build on errors (and optionally
-warnings). Pin the template to a reviewed tag or commit before enabling it as a
+`examples/README.md` contains a GitHub Actions template for installing the pack from
+PyPI, validating a rules directory, and failing the build on errors (and optionally
+warnings). Pin the install to a reviewed release version before enabling it as a
 quality gate.
 
 ## Rule Pack Model

{appsec_rules_pack-0.2.0 → appsec_rules_pack-0.3.0}/pyproject.toml

@@ -80,5 +80,7 @@ branch = true
 source = ["appsec_rules_pack"]
 
 [tool.coverage.report]
-fail_under = 90
+# Raised from 90 once actual coverage settled above 97%. A gate far below the real
+# number permits a silent regression the size of the gap.
+fail_under = 95
 show_missing = true

{appsec_rules_pack-0.2.0 → appsec_rules_pack-0.3.0}/src/appsec_rules_pack/__init__.py

@@ -2,4 +2,4 @@
 
 __all__ = ["__version__"]
 
-__version__ = "0.2.0"
+__version__ = "0.3.0"

{appsec_rules_pack-0.2.0 → appsec_rules_pack-0.3.0}/src/appsec_rules_pack/cli.py

@@ -111,6 +111,23 @@ def _format_file_issue(base_path: Path, file_path: Path, issue: ValidationIssue)
     return f"{_display_path(base_path, file_path)}: {_format_issue(issue)}"
 
 
+def _write_document(output: Path, document: str) -> None:
+    """Write a derived document, reporting write failures as an actionable CLI error.
+
+    Pointing ``--output`` at an existing directory, or at any path that cannot be
+    written, used to escape as a raw Python traceback (``PermissionError`` on Windows,
+    ``IsADirectoryError`` on POSIX). The caller keeps its own success message.
+    """
+
+    try:
+        output.parent.mkdir(parents=True, exist_ok=True)
+        output.write_text(document, encoding="utf-8", newline="\n")
+    except OSError as error:
+        reason = error.strerror or str(error)
+        typer.echo(f"Write failed: cannot write to {output}: {reason}.", err=True)
+        raise typer.Exit(code=1) from error
+
+
 def _iter_rule_files(path: Path) -> tuple[Path, ...]:
     if path.is_file():
         return (path,)
@@ -273,8 +290,7 @@ def export_index(
     document = json.dumps(index, indent=2) + "\n"
 
     if output is not None:
-        output.parent.mkdir(parents=True, exist_ok=True)
-        output.write_text(document, encoding="utf-8")
+        _write_document(output, document)
         typer.echo(f"Wrote index for {_plural(len(rule_files), 'file', 'files')} to {output}.")
         return
 
@@ -302,8 +318,7 @@ def export_semgrep(
     document = SEMGREP_HEADER + body
 
     if output is not None:
-        output.parent.mkdir(parents=True, exist_ok=True)
-        output.write_text(document, encoding="utf-8")
+        _write_document(output, document)
         typer.echo(
             f"Wrote Semgrep scaffold for {_plural(len(rule_files), 'file', 'files')} to {output}."
         )
@@ -332,8 +347,7 @@ def export_sarif(
     document = json.dumps(sarif, indent=2) + "\n"
 
     if output is not None:
-        output.parent.mkdir(parents=True, exist_ok=True)
-        output.write_text(document, encoding="utf-8")
+        _write_document(output, document)
         typer.echo(
             f"Wrote SARIF rule-catalog for {_plural(len(rule_files), 'file', 'files')} to {output}."
         )
@@ -360,11 +374,21 @@ def report_coverage(
 
     coverage = build_coverage_from_files(list(rule_files))
 
+    if coverage["rules"] == 0:
+        # The report is derived without schema validation, so a pack whose `rules` key is
+        # missing or malformed still produces a clean-looking 0/0 report. Say so on stderr
+        # rather than letting an empty report read as a healthy one. The exit code stays 0:
+        # reporting is derivation, and `validate` is what judges pack structure.
+        typer.echo(
+            f"Warning: no rules found in {rules_path}; the coverage report is empty. "
+            "Run `validate` to check the pack structure.",
+            err=True,
+        )
+
     if output_format is OutputFormat.json:
         document = json.dumps(coverage, indent=2) + "\n"
         if output is not None:
-            output.parent.mkdir(parents=True, exist_ok=True)
-            output.write_text(document, encoding="utf-8")
+            _write_document(output, document)
             typer.echo(f"Wrote coverage report to {output}.")
             return
         typer.echo(document, nl=False)

{appsec_rules_pack-0.2.0 → appsec_rules_pack-0.3.0}/src/appsec_rules_pack/validator.py

@@ -181,14 +181,18 @@ def validate_rules_payload(payload: Any, *, require_examples: bool = False) -> V
     schema = _load_schema()
     validator = jsonschema.Draft202012Validator(schema)
 
+    # jsonschema reports one error per missing required property, but the rendered
+    # message names every missing field at that location. Three missing fields therefore
+    # produced three byte-identical lines, and inflated the reported error count. An
+    # identical level+path+message carries no extra information, so it is dropped.
+    seen_schema_issues: set[tuple[str, tuple[Any, ...]]] = set()
     for error in sorted(validator.iter_errors(payload), key=lambda item: list(item.path)):
-        issues.append(
-            ValidationIssue(
-                level="error",
-                message=_schema_issue_message(error),
-                path=tuple(error.absolute_path),
-            )
-        )
+        message = _schema_issue_message(error)
+        path = tuple(error.absolute_path)
+        if (message, path) in seen_schema_issues:
+            continue
+        seen_schema_issues.add((message, path))
+        issues.append(ValidationIssue(level="error", message=message, path=path))
 
     if isinstance(payload, dict):
         issues.extend(_semantic_issues(payload, require_examples=require_examples))