# Aqua rego conventions

## Policy Metadata

Each rego file will have a rule like the following:

__rego_metadata__ := {
    "id": "XYZ-1234"
    "title": "My rule",
    "version": "v1.0.0",
    "severity": "HIGH",
    "type": "Kubernetes Security Check",
}

1. The rule SHOULD be the first rule in the document.
1. The rule name MUST be `__rego_metadata__`.
1. The value MUST be JSON literal. In other words, it cannot use Rego expressions.
1. The rule MUST have the fields: "id", "title", "version". The rule CAN have any other fields like "severity" and "type".
1. "version" field is any string, it is not required to be a semver.
1. "id" MUST be restricted to `[A-Z][0-9][_-]+`.
1. TBD: use the same "id" format across projects? `[A-Z]3-[0-9]+`. For example: `APS-1234`. The numerical part of "id" is a running number for the policy that MUST be unique within the scope of the prefix.
1. "title" is any textual user friendly description of the policy. There are no restrictions on it.

## entrypoint

The policy's entrypoint is the rule that is evaluated in order to query the policy decision. It MUST be in the following format:

deny[res] {
    #checks...
    res := {
    	"msg": "decision message",
        "id":  __rego_metadata__.id,
        "title": __rego_metadata__.title,
        "severity": __rego_metadata__.severity
        "type":  __rego_metadata__.type
    }
}

1. The entrypoint MUST be a "partial set" rule.
2. The entrypoint's result must be an object with the fields: "msg", and all of the top level fields of the policy metadata.
3. The entrypoint CAN use a helper function to construct the result.
4. The "msg" field is a user friendly message that describes the policy's decision.
5. The entrypoint CAN be tested for it's correctness, but it MUST be tested for returning a valid result in the desired format.

## Policy files

1. The Rego package name MUST be in the format of `$namespace.$policyid`.
1. `$namespace` MUST start with a domain name such as `appshield` and `tracee`. For example:`tracee.APS_1234`.
2. `$namespace` can include a config type such as `kubernetes` and `dockerfile`. For example: `appshield.dockerfile.APS_1234`.
3. If "id" contains `-`, it must be translated into `_`, For example: `appshield.kubernetes.APS_1234`.
1. If the policy has a config type in the Rego package name, the file SHOULD be under the `$configtype` directory. For example: `kubernetes/APS-1234.rego`.
1. Policies MUST have an accompanied test file with the name `$policyid_test.rego`. For example: `APS-1234_test.rego`.