You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Keep provider discovery, parsers, and cloud SDK calls in `@cloudburn/sdk`. Rule files in
56
-
`@cloudburn/rules` should stay pure and expose evaluators over normalized inputs.
57
-
58
-
4. Export it from service `index.ts` and provider `index.ts`.
59
-
5. Ensure preset inclusion when appropriate (`presets/aws-core.ts`).
60
-
6. Add or update tests in `packages/rules/test`.
61
-
62
-
## Rule Metadata Expectations
63
-
64
-
- IDs use the `CLDBRN-{PROVIDER}-{SERVICE}-{N}` format (uppercase, no zero-padding, sequential per service).
65
-
- Keep descriptions user-facing and actionable.
66
-
- Keep `message` as the generic public policy text for grouped scan output.
67
-
- Prefer `supports: ['iac', 'discovery']` only when both are implemented.
68
-
- Use `supports: ['discovery']` or `supports: ['iac']` when a rule only has one real evaluator.
69
-
-`CLDBRN-AWS-EBS-1` (`volume-type-current-gen`) is the reference example for a rule supporting both discovery and IaC evaluation.
70
-
71
-
## Testing Guidance for Rules
72
-
73
-
- Add metadata/export coverage.
74
-
- Add focused unit tests for rule behavior once rule logic is implemented.
75
-
- Keep fixtures small and deterministic.
44
+
See [`docs/guides/adding-a-rule.md`](docs/guides/adding-a-rule.md) for the full end-to-end walkthrough covering file placement, `createRule`, dataset dependencies, tests, and registration.
76
45
77
46
## Changesets
78
47
79
-
Use Changesets for user-facing package changes:
80
-
81
-
```bash
82
-
pnpm changeset
83
-
```
48
+
Write `.changeset/<slug>.md` files directly for user-facing package changes. Published packages: `cloudburn` (cli), `@cloudburn/sdk`, `@cloudburn/rules`.
84
49
85
-
Add the generated `.changeset/*.md` file to your PR when it changes a published package
86
-
(`cloudburn` (cli), `@cloudburn/sdk`, or `@cloudburn/rules`).
50
+
One changeset file per package — never list multiple packages in one file.
87
51
88
52
Do not run the versioning step in feature PRs. Versioning happens in the automated
`@cloudburn/rules` must stay pure — no I/O, no AWS SDK, no engine imports.
11
+
Dependency direction is **`cli -> sdk -> rules`**. No reverse imports. `@cloudburn/rules` must stay pure — no I/O, no AWS SDK, no engine imports.
18
12
19
13
## Finding Shape Gotchas
20
14
21
-
Output is a three-level hierarchy: `providers -> rules -> findings`.
15
+
Output is a three-level hierarchy: `providers -> rules -> findings`. See [`docs/reference/finding-shape.md`](reference/finding-shape.md) for full type contracts.
22
16
23
17
-`source` (`'discovery' | 'iac'`) and `message` live on the rule group (`Finding`), not on `FindingMatch` or `ScanResult`.
24
18
- Evaluators return one grouped `Finding` or `null` — never a flat array, never an empty `findings: []`.
@@ -28,40 +22,33 @@ Output is a three-level hierarchy: `providers -> rules -> findings`.
28
22
29
23
## Rule Conventions
30
24
25
+
See [`docs/guides/adding-a-rule.md`](guides/adding-a-rule.md) for the full authoring guide and [`docs/reference/rule-ids.md`](reference/rule-ids.md) for ID conventions.
26
+
27
+
Key reviewer checks:
28
+
31
29
- All rules must use `createRule()`.
32
-
- Rule IDs follow `CLDBRN-{PROVIDER}-{SERVICE}-{N}`. No zero-padding.
33
-
- IDs are permanent — never renumber, even if a rule is removed.
34
30
- Rule names describe the policy, not the remediation.
35
-
- The canonical `message` is set once on the `Rule` object and must work for both `discovery` and `iac`.
36
31
- Only implement evaluators for modes declared in `supports`.
37
-
- Static-capable rules with `evaluateStatic` must declare `staticDependencies`.
38
-
- Discovery-capable rules with `evaluateLive` must declare `discoveryDependencies`.
39
32
- Rules must not declare Terraform type strings, CloudFormation type strings, Resource Explorer `resourceTypes`, or loader wiring directly.
40
-
- Static evaluators should read from `StaticEvaluationContext.resources.get('<dataset-key>')`.
41
-
- Discovery evaluators should read from `LiveEvaluationContext.resources.get('<dataset-key>')`.
42
33
43
34
## Testing Layers
44
35
45
-
Vitest across all three packages. When adding or modifying a rule, all three test layers must be updated:
36
+
See [`docs/TESTING.md`](TESTING.md) for the full test strategy and mock boundaries.
37
+
38
+
When adding or modifying a rule, all three `@cloudburn/rules` test layers must be updated:
@@ -51,6 +52,7 @@ All stdout-producing commands return a typed `CliResponse` and share the same fo
51
52
-`discover --region <region>` overrides the current AWS region resolved from `AWS_REGION`, `AWS_DEFAULT_REGION`, `aws_region`, then the AWS SDK region provider chain.
52
53
- The CLI targets one explicit AWS region per discover run.
53
54
- Multi-region discovery remains an SDK capability through `target: { mode: 'regions', regions: [...] }` and requires a Resource Explorer aggregator index.
55
+
-`discover status` reports the current Resource Explorer index state and uses the shared `json|table` renderer.
54
56
-`discover supported-resource-types` uses the shared `json|table` renderer.
55
57
-`discover init` bootstraps Resource Explorer through the SDK, defaults to the current AWS region, accepts `--region <region>` as an override, and falls back to local-only setup when cross-region bootstrap is denied.
56
58
-`discover init` status output includes the resolved setup `indexType` so users can distinguish local-only setup from aggregator setup.
Rules now return a single grouped `Finding` or `null`. The SDK is responsible for regrouping those rule findings under providers in the public `ScanResult`.
61
+
Rules return a single grouped `Finding` or `null`. The SDK regroups those rule findings under providers in the public `ScanResult`.
62
62
63
63
## Rule Assembly Chain
64
64
@@ -73,56 +73,8 @@ graph LR
73
73
74
74
## Authoring Rules
75
75
76
-
1. Use `createRule({ ... })`.
77
-
2. Keep the stable rule metadata, including the canonical public `message`, on the `Rule` object itself.
78
-
3. For static IaC rules, declare `staticDependencies` dataset keys.
79
-
4. For live AWS rules, declare `discoveryDependencies` dataset keys.
80
-
5. Build lean resource-level `FindingMatch` values inside the evaluator.
81
-
6. Return `{ ruleId, service, source, message, findings }` when there are matches.
82
-
7. Return `null` when nothing matches.
83
-
84
-
Rule evaluators consume static and live datasets through `context.resources.get('<dataset-key>')`. Rules should not declare Terraform resource type strings, CloudFormation type strings, Resource Explorer `resourceTypes`, or loader wiring directly.
85
-
86
-
## ID Convention
87
-
88
-
-**Rule ID:**`CLDBRN-{PROVIDER}-{SERVICE}-{N}`
89
-
- Rule IDs remain stable and drive presets, configuration, and public scan output.
90
-
- There are no per-resource finding IDs in the public rules contract anymore.
76
+
See [`docs/guides/adding-a-rule.md`](../guides/adding-a-rule.md) for the full end-to-end guide and [`docs/reference/rule-ids.md`](../reference/rule-ids.md) for the ID convention and complete rule table.
`CLDBRN-AWS-LAMBDA-1` is an advisory rule. It recommends `arm64` only when compatibility is known or explicitly declared, and the static evaluator skips computed or otherwise unknown architecture values instead of treating them as definite `x86_64`.
123
-
124
-
CloudTrail and CloudWatch discovery rules now rely on dedicated live datasets. CloudBurn seeds both CloudWatch datasets from Resource Explorer `logs:log-group` catalog results, then uses narrow CloudWatch Logs APIs to hydrate group retention metadata and enumerate log streams.
125
-
126
-
EBS discovery rules now reuse the shared `aws-ebs-volumes` dataset for storage type, attachment, size, and IOPS checks, and use a dedicated `aws-ebs-snapshots` dataset seeded from Resource Explorer `ec2:snapshot` resources for snapshot-age review.
127
-
128
-
NAT gateway and SageMaker notebook discovery follow the same catalog-first model: CloudBurn seeds NAT review from `ec2:natgateway` resources and hydrates 7-day traffic totals with `DescribeNatGateways` plus CloudWatch metrics, while SageMaker notebook review is seeded from `sagemaker:notebook-instance` resources and hydrated through `DescribeNotebookInstance`.
80
+
See [`docs/reference/rule-ids.md`](../reference/rule-ids.md) for the complete rule table with descriptions and support modes.
0 commit comments