Motivation

Custom rule authors writing Rego policies need to know immediately whether their code is valid, not after a failed deployment. This PR adds two new exported functions, ValidateCustomRegoQuery and RunCustomRegoQuery, that give callers IDE-quality diagnostics and evaluation results for custom Rego rules without running a full scan.

Related Ticket: K9CODESEC-2398

Changes

Validation pipeline

ValidateCustomRegoQuery runs three phases in a single call and returns all errors simultaneously, so authors see the full picture at once rather than fixing one error at a time:

1. Parse: OPA parse errors are rewritten into actionable messages. Bare .document references (missing input prefix), missing package declarations, missing commas inside objects, and unbalanced parentheses each get a precise line/column location and a human-readable explanation instead of OPA's internal error text.
2. Static AST checks: verifies that the package is datadog, that a DatadogPolicy rule is present, that all required result fields (documentId, resourceType, resourceName, searchKey) are assigned, that sprintf call matches its format string, and that any aliased library has a corresponding import statement.
3. OPA compilation: compiles the rule against the platform libraries and surfaces type errors and unresolved references. Errors that are purely a consequence of an earlier structural problem (wrong package, missing rule, missing import) are filtered out so they do not drown out the root cause.

If the module is missing its package declaration, validation recovers by temporarily prepending package datadog, runs the static checks on the recovered AST, and shifts error line numbers back so locations still point at the user's original code.

Evaluation

RunCustomRegoQuery writes the Rego content and the IaC file to temporary files with the correct platform-specific extension (.tf, .yaml, .json, …), runs the scan engine in-memory, and returns findings with precise resource locations alongside any runtime errors.

CLI

Two new subcommands are registered under custom:

datadog-iac-scanner custom validate --platform <platform> --rego <base64> — outputs JSON {"errors": [...]}.

datadog-iac-scanner custom evaluate --platform <platform> --rego <base64> --file <base64> — runs validation first; if errors are found they are returned without scanning. Otherwise outputs JSON {"findings": [...], "errors": [...]}.

Both commands accept base64-encoded inputs so binary-safe content can be passed from any calling process without shell escaping concerns.

Author Checklist

• I have reviewed my own PR.
• I have added or updated relevant unit tests where necessary. If no tests are added, I've explained why.
• All new and existing tests pass.
• I have tested my changes on staging (if applicable).
• I have updated any relevant documentation (if applicable).

QA Instruction

1. go test ./pkg/scan/ -run TestValidateCustomRegoQuery -v — all scenarios (missing package, wrong package, missing rule, missing result fields, missing imports, missing commas, unbalanced parens, missing input, undefined variables) should pass.
2. Build: go build ./cmd/scanner/...
3. Validate a known-good rule end-to-end:

REGO=$(base64 -i <path-to-valid-rule.rego>)
./bin/datadog-iac-scanner custom validate --platform terraform --rego "$REGO"
# expect: {"errors": []}

4. Introduce a deliberate error (remove resourceType from the result object) and re-run validate — expect a missing_result_field error with the correct line number.
5. Evaluate against a sample Terraform file:

FILE=$(base64 -i <path-to-sample.tf>)
./bin/datadog-iac-scanner custom evaluate --platform terraform --rego "$REGO" --file "$FILE"
# expect: {"findings": [...], "errors": []}

Blast Radius

This PR only adds new exported functions and CLI subcommands. No existing scan logic, query loading, or result reporting paths are modified. The only change to existing files is wiring the new custom command into the CLI entry point and a minor fix to pass the IaC file path through the scan client.

Additional Notes

I submit this contribution under the Apache-2.0 license.