feat(rules): Add Framework object for structured compliance metadata

[jychp]

Type of change

• New feature (non-breaking change that adds functionality)

Summary

This PR introduces a Framework dataclass to link rules to compliance frameworks (CIS, NIST, etc.) with structured fields for filtering and querying.

Key changes:

• Framework class: New dataclass with name, short_name, requirement, scope, and revision fields. All fields are normalized to lowercase for case-insensitive comparison.
• Rule.frameworks: Rules can now declare compliance framework references via a frameworks tuple.
• Rule.has_framework(): Method to check if a rule matches given framework criteria.
• CLI enhancements:
  • --framework / -f filter option for list and run commands
  • New frameworks command to list all compliance frameworks
  • Auto-select all rules when --framework is provided without a rule argument
• Runner functions: get_all_frameworks() and filter_rules_by_framework() for programmatic filtering.
• RuleResult: Now exposes rule_tags and rule_frameworks for downstream consumers.
• Migration: All existing CIS rules migrated to use Framework objects.

Example usage:

# List all CIS rules
cartography-rules list --framework CIS

# Run only CIS AWS 5.0 rules
cartography-rules run --framework CIS:aws:5.0

# List available frameworks
cartography-rules frameworks

How was this tested?

• make test_unit - 483 tests passed
• make test_lint - All checks passed
• Manual CLI testing with --framework filter

Checklist

General

• I have read the contributing guidelines.
• The linter passes locally (make lint).
• I have added/updated tests that prove my fix is effective or my feature works.

Proof of functionality

• New or updated unit/integration tests.

Notes for reviewers

This 'tag' approach for linking to a Framework was chosen (rather than the old composition system where a rule only existed for one framework) to offer maximum flexibility and reusability.

This design follows the existing pattern in the codebase and enables downstream systems like SubImage to build rule collections based on compliance frameworks.

[cubic-dev-ai]

3 issues found across 13 files

Prompt for AI agents (all issues)

Check if these issues are valid — if so, understand the root cause of each and fix them.


<file name="cartography/rules/data/rules/cis_aws_networking.py">

<violation number="1" location="cartography/rules/data/rules/cis_aws_networking.py:107">
P2: The `cis:aws-5.0` tag was removed from this rule, but no `Framework` object was added to replace it. Since `unrestricted_all_ports` explicitly references `CIS_REFERENCES`, it implies this rule is part of the CIS benchmark (or at least related).

If this rule is part of the framework, it must be migrated to use the `Framework` object (like the other rules in this file) to be discoverable via the new `--framework` CLI filter. If it is *not* part of the framework, consider removing `CIS_REFERENCES` to avoid confusion.</violation>
</file>

<file name="tests/unit/rules/test_runners.py">

<violation number="1" location="tests/unit/rules/test_runners.py:46">
P2: The tests update `mock_rule` with `tags` and `frameworks`, but do not verify that these values are correctly propagated to the `RuleResult`.
(Based on your team's feedback about ensuring tests exercise the change they claim to validate.) [FEEDBACK_USED]</violation>
</file>

<file name="cartography/rules/data/rules/cis_google_workspace.py">

<violation number="1" location="cartography/rules/data/rules/cis_google_workspace.py:96">
P2: The scope 'google_workspace' is inconsistent with the standard module identifier 'googleworkspace' used in `Module.GOOGLEWORKSPACE`, previous tags (e.g., `cis:googleworkspace-1.4`), and the internal `MODULE_TO_CARTOGRAPHY_INTEL` mapping.

Using the standard identifier 'googleworkspace' ensures consistency across CLI filters, internal metadata, and potential downstream consumers.

(Note: Tests asserting this scope string may also need updates.)</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[kunaals]

this seems great! one small nit: might be good to add details about Frameworks in the create-rule.md doc

[kunaals]

i think extra character got left behind

[jychp]

\b is the Typer/Click literal block marker.