appsec-rules-pack 0.2.0__py3-none-any.whl

appsec_rules_pack/__init__.py

@@ -0,0 +1,5 @@
+"""AppSec rules pack validator package."""
+
+__all__ = ["__version__"]
+
+__version__ = "0.2.0"

appsec_rules_pack/__main__.py

@@ -0,0 +1,5 @@
+"""Module entry point for the AppSec rules pack CLI."""
+
+from appsec_rules_pack.cli import app
+
+app()

appsec_rules_pack/cli.py

@@ -0,0 +1,384 @@
+"""Typer command-line interface for AppSec rules pack validation."""
+
+import json
+from enum import StrEnum
+from pathlib import Path
+from typing import Annotated
+
+import typer
+import yaml
+
+from appsec_rules_pack import __version__
+from appsec_rules_pack.exporter import build_index_from_files
+from appsec_rules_pack.reporter import build_coverage_from_files
+from appsec_rules_pack.sarif_export import build_sarif_from_files
+from appsec_rules_pack.semgrep_scaffold import (
+    PATTERN_PLACEHOLDER,
+    build_semgrep_scaffold_from_files,
+)
+from appsec_rules_pack.validator import (
+    ValidationIssue,
+    ValidationResult,
+    validate_rules_file,
+    validate_rules_files,
+)
+
+app = typer.Typer(help="Validate AppSec rules pack files.")
+export_app = typer.Typer(help="Derive machine-readable artifacts from rules packs.")
+app.add_typer(export_app, name="export")
+report_app = typer.Typer(help="Derive coverage and summary reports from rules packs.")
+app.add_typer(report_app, name="report")
+
+
+class OutputFormat(StrEnum):
+    """Supported validation output formats."""
+
+    text = "text"
+    json = "json"
+
+
+RulesPathArg = Annotated[
+    Path,
+    typer.Argument(exists=True, file_okay=True, dir_okay=True),
+]
+FailOnWarningsOpt = Annotated[
+    bool,
+    typer.Option(
+        "--fail-on-warnings",
+        help="Return a non-zero exit code when warnings are present.",
+    ),
+]
+RequireExamplesOpt = Annotated[
+    bool,
+    typer.Option(
+        "--require-examples",
+        help="Warn when an enabled rule has no compliant and violating examples.",
+    ),
+]
+FormatOpt = Annotated[
+    OutputFormat,
+    typer.Option(
+        "--format",
+        "-f",
+        help="Output format: text (default) or json.",
+    ),
+]
+RULE_FILE_SUFFIXES = frozenset((".yaml", ".yml"))
+
+SEMGREP_HEADER = (
+    "# Reference Semgrep scaffold derived from the AppSec Rules Pack (derivation only).\n"
+    "# NOT a runnable ruleset: the source rules are engine-agnostic review rules with no\n"
+    "# detection patterns (see ADR-0001). Replace each rule's placeholder pattern-regex\n"
+    f"# ('{PATTERN_PLACEHOLDER}') with a real detection before use. Only enabled rules are\n"
+    "# emitted. Regenerate: appsec-rules export semgrep <rules> -o <out>.semgrep.yaml\n"
+)
+
+
+class IndexFormat(StrEnum):
+    """Supported export index formats."""
+
+    json = "json"
+
+
+IndexFormatOpt = Annotated[
+    IndexFormat,
+    typer.Option("--format", "-f", help="Index output format (json)."),
+]
+IndexOutputOpt = Annotated[
+    Path | None,
+    typer.Option("--output", "-o", help="Write the index to this file instead of stdout."),
+]
+
+
+def _issue_path_str(issue: ValidationIssue) -> str:
+    return ".".join(str(part) for part in issue.path) if issue.path else "<root>"
+
+
+def _format_issue(issue: ValidationIssue) -> str:
+    return f"{issue.level.upper()} {_issue_path_str(issue)}: {issue.message}"
+
+
+def _display_path(base_path: Path, file_path: Path) -> str:
+    if base_path.is_file():
+        return file_path.name
+    try:
+        return str(file_path.relative_to(base_path))
+    except ValueError:
+        return str(file_path)
+
+
+def _format_file_issue(base_path: Path, file_path: Path, issue: ValidationIssue) -> str:
+    return f"{_display_path(base_path, file_path)}: {_format_issue(issue)}"
+
+
+def _iter_rule_files(path: Path) -> tuple[Path, ...]:
+    if path.is_file():
+        return (path,)
+
+    return tuple(
+        sorted(
+            (
+                file_path
+                for file_path in path.rglob("*")
+                if file_path.is_file() and file_path.suffix.lower() in RULE_FILE_SUFFIXES
+            ),
+            key=lambda file_path: str(file_path).lower(),
+        )
+    )
+
+
+def _plural(count: int, singular: str, plural: str) -> str:
+    noun = singular if count == 1 else plural
+    return f"{count} {noun}"
+
+
+def _summarize(results: tuple[ValidationResult, ...]) -> tuple[int, int, int]:
+    rule_count = sum(result.rule_count for result in results)
+    error_count = sum(result.error_count for result in results)
+    warning_count = sum(result.warning_count for result in results)
+    return rule_count, error_count, warning_count
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        typer.echo(f"appsec-rules {__version__}")
+        raise typer.Exit()
+
+
+VersionOpt = Annotated[
+    bool,
+    typer.Option(
+        "--version",
+        callback=_version_callback,
+        is_eager=True,
+        help="Show the installed version and exit.",
+    ),
+]
+
+
+@app.callback()
+def main(version: VersionOpt = False) -> None:
+    """Run AppSec rules pack commands."""
+
+
+def _build_report(
+    rules_path: Path,
+    file_results: tuple[tuple[Path, ValidationResult], ...],
+) -> dict:
+    rule_count, error_count, warning_count = _summarize(tuple(result for _, result in file_results))
+    files = [
+        {
+            "path": _display_path(rules_path, rule_file),
+            "rules": result.rule_count,
+            "errors": result.error_count,
+            "warnings": result.warning_count,
+            "issues": [
+                {
+                    "level": issue.level,
+                    "path": _issue_path_str(issue),
+                    "message": issue.message,
+                }
+                for issue in result.issues
+            ],
+        }
+        for rule_file, result in file_results
+    ]
+    return {
+        "summary": {
+            "files": len(file_results),
+            "rules": rule_count,
+            "errors": error_count,
+            "warnings": warning_count,
+        },
+        "files": files,
+    }
+
+
+@app.command()
+def validate(
+    rules_path: RulesPathArg,
+    fail_on_warnings: FailOnWarningsOpt = False,
+    require_examples: RequireExamplesOpt = False,
+    output_format: FormatOpt = OutputFormat.text,
+) -> None:
+    """Validate one YAML rules pack file or a directory of YAML rule packs."""
+
+    rule_files = _iter_rule_files(rules_path)
+    if not rule_files:
+        if output_format is OutputFormat.json:
+            typer.echo(
+                json.dumps(
+                    {
+                        "summary": {"files": 0, "rules": 0, "errors": 1, "warnings": 0},
+                        "files": [],
+                        "error": f"no YAML rule files found in {rules_path}",
+                    },
+                    indent=2,
+                )
+            )
+        else:
+            typer.echo(f"Validation failed: no YAML rule files found in {rules_path}.")
+        raise typer.Exit(code=1)
+
+    if len(rule_files) == 1:
+        file_results = (
+            (rule_files[0], validate_rules_file(rule_files[0], require_examples=require_examples)),
+        )
+    else:
+        file_results = validate_rules_files(rule_files, require_examples=require_examples)
+
+    rule_count, error_count, warning_count = _summarize(tuple(result for _, result in file_results))
+    ok = error_count == 0
+    passed = ok and not (fail_on_warnings and warning_count)
+
+    if output_format is OutputFormat.json:
+        report = _build_report(rules_path, file_results)
+        report["summary"]["ok"] = passed
+        typer.echo(json.dumps(report, indent=2))
+        if not passed:
+            raise typer.Exit(code=1)
+        return
+
+    for rule_file, result in file_results:
+        for issue in result.issues:
+            typer.echo(_format_file_issue(rules_path, rule_file, issue))
+
+    file_summary = _plural(len(rule_files), "file", "files")
+    verdict = "passed" if passed else "failed"
+    typer.echo(
+        f"Validation {verdict}: {file_summary}, {rule_count} rules, "
+        f"{error_count} errors, {warning_count} warnings."
+    )
+    if not passed:
+        raise typer.Exit(code=1)
+
+
+@export_app.command("index")
+def export_index(
+    rules_path: RulesPathArg,
+    output_format: IndexFormatOpt = IndexFormat.json,
+    output: IndexOutputOpt = None,
+) -> None:
+    """Derive a machine-readable JSON index from a rules pack file or directory.
+
+    Derivation only: this reads pack and rule metadata and never executes rules.
+    """
+
+    rule_files = _iter_rule_files(rules_path)
+    if not rule_files:
+        typer.echo(f"Export failed: no YAML rule files found in {rules_path}.", err=True)
+        raise typer.Exit(code=1)
+
+    index = build_index_from_files(list(rule_files))
+    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")
+        typer.echo(f"Wrote index for {_plural(len(rule_files), 'file', 'files')} to {output}.")
+        return
+
+    typer.echo(document, nl=False)
+
+
+@export_app.command("semgrep")
+def export_semgrep(
+    rules_path: RulesPathArg,
+    output: IndexOutputOpt = None,
+) -> None:
+    """Derive a NON-RUNNABLE reference Semgrep scaffold (derivation only).
+
+    The scaffold carries rule metadata but placeholder patterns; it is not a working
+    ruleset and must have real detections added before use (see ADR-0001).
+    """
+
+    rule_files = _iter_rule_files(rules_path)
+    if not rule_files:
+        typer.echo(f"Export failed: no YAML rule files found in {rules_path}.", err=True)
+        raise typer.Exit(code=1)
+
+    scaffold = build_semgrep_scaffold_from_files(list(rule_files))
+    body = yaml.safe_dump(scaffold, sort_keys=False, allow_unicode=True)
+    document = SEMGREP_HEADER + body
+
+    if output is not None:
+        output.parent.mkdir(parents=True, exist_ok=True)
+        output.write_text(document, encoding="utf-8")
+        typer.echo(
+            f"Wrote Semgrep scaffold for {_plural(len(rule_files), 'file', 'files')} to {output}."
+        )
+        return
+
+    typer.echo(document, nl=False)
+
+
+@export_app.command("sarif")
+def export_sarif(
+    rules_path: RulesPathArg,
+    output: IndexOutputOpt = None,
+) -> None:
+    """Derive a SARIF 2.1.0 rule-catalog (reportingDescriptors, no results).
+
+    The pack does not execute, so the SARIF ``results`` array is intentionally empty;
+    this publishes the rule catalog and metadata for SARIF-aware tools (see ADR-0001).
+    """
+
+    rule_files = _iter_rule_files(rules_path)
+    if not rule_files:
+        typer.echo(f"Export failed: no YAML rule files found in {rules_path}.", err=True)
+        raise typer.Exit(code=1)
+
+    sarif = build_sarif_from_files(list(rule_files))
+    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")
+        typer.echo(
+            f"Wrote SARIF rule-catalog for {_plural(len(rule_files), 'file', 'files')} to {output}."
+        )
+        return
+
+    typer.echo(document, nl=False)
+
+
+@report_app.command("coverage")
+def report_coverage(
+    rules_path: RulesPathArg,
+    output_format: FormatOpt = OutputFormat.text,
+    output: IndexOutputOpt = None,
+) -> None:
+    """Report framework-mapping coverage across a rules pack.
+
+    Derivation only: this summarizes mapping metadata and never executes rules.
+    """
+
+    rule_files = _iter_rule_files(rules_path)
+    if not rule_files:
+        typer.echo(f"Report failed: no YAML rule files found in {rules_path}.", err=True)
+        raise typer.Exit(code=1)
+
+    coverage = build_coverage_from_files(list(rule_files))
+
+    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")
+            typer.echo(f"Wrote coverage report to {output}.")
+            return
+        typer.echo(document, nl=False)
+        return
+
+    total = coverage["rules"]
+    typer.echo(f"Mapping coverage for {_plural(total, 'rule', 'rules')}:")
+    for framework, stats in coverage["frameworks"].items():
+        covered = stats["covered"]
+        pct = round(100 * covered / total) if total else 0
+        line = f"  {framework:<22} {covered}/{total}  ({pct}%)"
+        if stats["missing"]:
+            line += "  missing: " + ", ".join(stats["missing"])
+        typer.echo(line)
+    if coverage["categories"]:
+        cats = ", ".join(f"{name}={count}" for name, count in coverage["categories"].items())
+        typer.echo(f"Categories: {cats}")

appsec_rules_pack/exporter.py

@@ -0,0 +1,66 @@
+"""Derive a machine-readable index from rules pack files.
+
+This module only *reads and derives* metadata from a rules pack. It never executes
+rules, scans code, or emits findings/SARIF, so it preserves the engine-agnostic
+boundary of the validator (see ADR-0001).
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from appsec_rules_pack.loader import load_yaml_file
+
+INDEX_SCHEMA = "appsec-rules-index/v1"
+
+# Per-rule fields copied into the index. Derivation only: no rule body, match
+# logic, examples, or evidence snippets are executed or expanded.
+_RULE_FIELDS = (
+    "id",
+    "title",
+    "severity",
+    "category",
+    "status",
+    "enforcement",
+    "targets",
+    "mappings",
+    "deprecation",
+)
+_PACK_FIELDS = ("id", "name", "version")
+
+
+def _pack_summary(payload: Any) -> dict[str, Any]:
+    pack = payload.get("pack") if isinstance(payload, dict) else None
+    if not isinstance(pack, dict):
+        return {}
+    return {field: pack[field] for field in _PACK_FIELDS if field in pack}
+
+
+def _rule_summary(rule: Any) -> dict[str, Any]:
+    if not isinstance(rule, dict):
+        return {}
+    return {field: rule[field] for field in _RULE_FIELDS if field in rule}
+
+
+def build_pack_index(payload: Any) -> dict[str, Any]:
+    """Build the index entry for a single rules pack payload."""
+
+    rules = payload.get("rules") if isinstance(payload, dict) else None
+    rule_entries = [_rule_summary(rule) for rule in rules] if isinstance(rules, list) else []
+    return {"pack": _pack_summary(payload), "rules": rule_entries}
+
+
+def build_index(payloads: list[Any]) -> dict[str, Any]:
+    """Build the full index document from one or more pack payloads."""
+
+    return {
+        "schema": INDEX_SCHEMA,
+        "packs": [build_pack_index(payload) for payload in payloads],
+    }
+
+
+def build_index_from_files(paths: list[Path]) -> dict[str, Any]:
+    """Load each YAML file and derive the index, preserving the given order."""
+
+    return build_index([load_yaml_file(path) for path in paths])

appsec_rules_pack/loader.py

@@ -0,0 +1,13 @@
+"""File loading helpers for AppSec rules pack validation."""
+
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+
+def load_yaml_file(path: Path) -> Any:
+    """Load a YAML file with safe parsing."""
+
+    with path.open("r", encoding="utf-8") as handle:
+        return yaml.safe_load(handle)

appsec_rules_pack/reporter.py

@@ -0,0 +1,80 @@
+"""Derive a framework-mapping coverage report from rules pack files.
+
+Derivation only: this reads mapping metadata and summarizes coverage. It never
+executes rules, scans code, or emits findings, so it preserves the engine-agnostic
+boundary of the validator (see ADR-0001).
+"""
+
+from __future__ import annotations
+
+from collections import Counter
+from pathlib import Path
+from typing import Any
+
+from appsec_rules_pack.loader import load_yaml_file
+
+COVERAGE_SCHEMA = "appsec-rules-coverage/v1"
+
+# Mapping frameworks reported. owasp_top_10_2025 is optional in the schema, so its
+# coverage is the informative one; the rest are required and should read 100%.
+_FRAMEWORKS = (
+    "owasp_asvs",
+    "owasp_api_top_10_2023",
+    "owasp_top_10_2025",
+    "cwe",
+    "nist_ssdf",
+)
+
+
+def _rules(payload: Any) -> list[dict[str, Any]]:
+    rules = payload.get("rules") if isinstance(payload, dict) else None
+    if not isinstance(rules, list):
+        return []
+    return [rule for rule in rules if isinstance(rule, dict)]
+
+
+def _has_mapping(rule: dict[str, Any], framework: str) -> bool:
+    mappings = rule.get("mappings")
+    if not isinstance(mappings, dict):
+        return False
+    values = mappings.get(framework)
+    return isinstance(values, list) and len(values) > 0
+
+
+def build_coverage(payloads: list[Any]) -> dict[str, Any]:
+    """Build a coverage report across one or more pack payloads."""
+
+    rules: list[dict[str, Any]] = []
+    for payload in payloads:
+        rules.extend(_rules(payload))
+
+    total = len(rules)
+    frameworks: dict[str, Any] = {}
+    for framework in _FRAMEWORKS:
+        missing = [
+            rule["id"]
+            for rule in rules
+            if not _has_mapping(rule, framework) and isinstance(rule.get("id"), str)
+        ]
+        frameworks[framework] = {
+            "covered": total - len(missing),
+            "total": total,
+            "missing": missing,
+        }
+
+    categories = Counter(
+        rule["category"] for rule in rules if isinstance(rule.get("category"), str)
+    )
+
+    return {
+        "schema": COVERAGE_SCHEMA,
+        "rules": total,
+        "frameworks": frameworks,
+        "categories": dict(sorted(categories.items())),
+    }
+
+
+def build_coverage_from_files(paths: list[Path]) -> dict[str, Any]:
+    """Load each YAML file and derive the coverage report."""
+
+    return build_coverage([load_yaml_file(path) for path in paths])

appsec_rules_pack/sarif_export.py

@@ -0,0 +1,108 @@
+"""Derive a SARIF rule-catalog export from the rules pack.
+
+Derivation only: this declares the pack's rules as SARIF reportingDescriptors
+(``tool.driver.rules``) with an EMPTY ``results`` array. The pack does not execute or
+scan code (see ADR-0001), so it produces no findings; this export lets SARIF-aware
+tools ingest the rule catalog and its metadata, not scan results.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from appsec_rules_pack.loader import load_yaml_file
+
+SARIF_VERSION = "2.1.0"
+SARIF_SCHEMA = "https://json.schemastore.org/sarif-2.1.0.json"
+TOOL_NAME = "AppSec Rules Pack"
+INFORMATION_URI = "https://github.com/lucashgrifoni/AppSec-Rules-Pack"
+
+# SARIF result levels and GitHub code-scanning security-severity bands.
+_LEVEL_MAP = {"critical": "error", "high": "error", "medium": "warning", "low": "note"}
+_SECURITY_SEVERITY = {"critical": "9.5", "high": "8.0", "medium": "5.0", "low": "2.0"}
+
+_PROPERTY_FIELDS = (
+    ("cwe", "cwe"),
+    ("owasp-asvs", "owasp_asvs"),
+    ("owasp-api-top-10-2023", "owasp_api_top_10_2023"),
+    ("owasp-top-10-2025", "owasp_top_10_2025"),
+    ("nist-ssdf", "nist_ssdf"),
+)
+
+
+def _descriptor(rule: dict[str, Any]) -> dict[str, Any]:
+    mappings = rule.get("mappings") if isinstance(rule.get("mappings"), dict) else {}
+    severity = rule.get("severity")
+
+    tags = ["security"]
+    if isinstance(rule.get("category"), str):
+        tags.append(rule["category"])
+    cwes = mappings.get("cwe")
+    if isinstance(cwes, list):
+        tags.extend(cwe for cwe in cwes if isinstance(cwe, str))
+
+    properties: dict[str, Any] = {"tags": tags}
+    if severity in _SECURITY_SEVERITY:
+        properties["security-severity"] = _SECURITY_SEVERITY[severity]
+    for out_key, field in _PROPERTY_FIELDS:
+        value = mappings.get(field)
+        if isinstance(value, list) and value:
+            properties[out_key] = list(value)
+
+    return {
+        "id": rule.get("id"),
+        "name": rule.get("id"),
+        "shortDescription": {"text": rule.get("title")},
+        "fullDescription": {"text": rule.get("description")},
+        "helpUri": INFORMATION_URI,
+        "defaultConfiguration": {"level": _LEVEL_MAP.get(severity, "warning")},
+        "properties": properties,
+    }
+
+
+def _tool_version(payloads: list[Any]) -> str:
+    for payload in payloads:
+        pack = payload.get("pack") if isinstance(payload, dict) else None
+        if isinstance(pack, dict) and isinstance(pack.get("version"), str):
+            return pack["version"]
+    return "0.0.0"
+
+
+def build_sarif(payloads: list[Any]) -> dict[str, Any]:
+    """Build a SARIF 2.1.0 rule-catalog document (no results) from pack payloads."""
+
+    descriptors: list[dict[str, Any]] = []
+    for payload in payloads:
+        rules = payload.get("rules") if isinstance(payload, dict) else None
+        if not isinstance(rules, list):
+            continue
+        descriptors.extend(
+            _descriptor(rule)
+            for rule in rules
+            if isinstance(rule, dict) and rule.get("status") == "enabled"
+        )
+
+    return {
+        "$schema": SARIF_SCHEMA,
+        "version": SARIF_VERSION,
+        "runs": [
+            {
+                "tool": {
+                    "driver": {
+                        "name": TOOL_NAME,
+                        "informationUri": INFORMATION_URI,
+                        "version": _tool_version(payloads),
+                        "rules": descriptors,
+                    }
+                },
+                "results": [],
+            }
+        ],
+    }
+
+
+def build_sarif_from_files(paths: list[Path]) -> dict[str, Any]:
+    """Load each YAML file and derive the SARIF rule-catalog document."""
+
+    return build_sarif([load_yaml_file(path) for path in paths])