Skip to content

policy.md

Latest commit

 

History

History
157 lines (125 loc) · 7 KB

policy.md

File metadata and controls

157 lines (125 loc) · 7 KB
Raw

Scan policy

A code_scanning policy decides which repositories are scanned, which engines run, how often, and what happens on pull requests. With no enabled policy, nothing is scanned.

Edit it in the console under Cloud Security → Policies → Code scanning, or store it as a record in the cloudsec_policy hive.

Example

policy_type: code_scanning
code_scanning:
  enabled: true
  repos:
    include: ["acme/api-*", "acme/payments"]
    exclude: ["acme/api-archive"]
  scanners:
    sca: true
    secrets: true
    secrets_history: true
    iac: true
    images: true
    licenses: true
    # sast runs unless set to false
  schedule: daily
  severity_floor: ""
  image_sources: ["dockerfile", "workloads"]
  pr_checks: true
  pr_comments: false
  gating:
    fail_on: HIGH
limacharlie hive set --hive-name cloudsec_policy --key code-scanning \
    --input-file code-policy.yaml --enabled

Save the YAML above as code-policy.yaml. Both enable switches matter: the Hive record must be enabled (--enabled), and its nested code_scanning.enabled must be true. Put repos, scanners and every field below inside code_scanning, not beside policy_type. A flat record is refused because it has no code-scanning body.

Fields

These fields belong to the nested code_scanning object.

Field Meaning
enabled Required. false keeps the policy but scans nothing.
repos.include Repositories to scan, as globs matched case-insensitively against owner/name and the bare name. Empty means every repository the connections can see.
repos.exclude Repositories to skip. Always wins over include.
scanners Which engines run. See Engines.
schedule daily (the default), weekly, or manual (no scheduled scan; an explicit rescan, provider sync or push webhook can still trigger one).
severity_floor Drop findings below this severity. See Severity floor.
sast_ruleset Deprecated and ignored. Old values (default, gitlab, custom:<ref>) are still accepted so existing records save, but static analysis always runs the organization's enabled code rules. Leave it out of new records.
image_sources Where the image engine finds images. See Container images.
pr_checks, pr_comments, gating.fail_on Pull-request checks on GitHub. fail_on is CRITICAL, HIGH, MEDIUM, LOW or NONE (the default). See Pull-request checks.
pr_live_context Live-impact disclosure on pull-request checks: off (default), risk_summary or resource_details. Least disclosure wins across policies. Requires the impact capability to be available. See Pull-request disclosure.
autofix_registry_access Whether AutoFix may look up package registry metadata to update lockfiles. Default true. See AutoFix.
ai_fix Reserved opt-in configuration for AI-proposed fixes. Currently unavailable. Saving this block does not enable the server capability.

Globs support *, ?, […], {a,b} and **. * does not cross a /, so acme/* does not select a GitLab subgroup project such as acme/platform/api. Use acme/** for that. A leading ! negates within a list. Write negations in include. A ! pattern in exclude means "exclude everything that does not match", which cancels your include list.

Engines

Key Engine Default
sca Dependencies and malicious packages off
secrets Secrets in the current files off
secrets_history Secrets in the full git history off
iac Infrastructure as code off
sast Static analysis on
images Container images off
licenses Dependency licenses off

Every engine except sast runs only when set to true. Static analysis runs unless a policy sets sast: false, and it runs the organization's enabled code rules. The console's policy form starts with dependencies, secrets, infrastructure as code, static analysis and licenses turned on.

An enabled policy needs at least one engine running.

secrets_history is a separate switch because it needs the full history instead of the latest commit. On a large repository that makes the scan much slower. Secrets found only in history need rotating: deleting the file does not un-leak the credential.

End-of-life runtime findings come with the dependency engine (sca) and the image engine (images).

Severity floor

severity_floor drops findings below a severity: MEDIUM, HIGH or CRITICAL. LOW, INFO and an empty value all mean no floor.

The floor drops findings rather than hiding them. A finding under the floor is never recorded. Raising the floor closes the findings that fall under it, with closed_reason: below_severity_floor. Lowering it again brings them back as new occurrences: their age restarts and their triage state is gone.

If you only want a narrower view, leave the floor empty and filter the worklist by severity.

Container images

image_sources is a list:

Value Scans
dockerfile Images your repositories reference, such as a Dockerfile's base image. The default. Links each image to the repository that builds it.
workloads Images your connected cloud accounts report running, when pinned by digest. Links each workload to the image it runs.
registries Accepted, but not built yet. It currently adds nothing.

Images are scanned only when scanners.images is true, and only when they are referenced by digest. A reference by tag alone is counted and skipped, because a tag can point at a different image tomorrow.

Image sources also decide what the code-to-runtime queries can see.

Several policies

An organization can have several code_scanning policies. For example, scan sensitive repositories daily with every engine, and everything else weekly with fewer engines. When more than one enabled policy selects a repository:

  • the engines are combined, so any policy can add one;
  • the lowest severity floor applies;
  • the most frequent schedule applies;
  • pull-request checks and comments are on if any policy turns them on, and the strictest gating.fail_on applies;
  • the image sources are combined;
  • autofix_registry_access: false in any policy wins, so a broad policy cannot restore network access a narrower policy removed.

Rescan now

To scan one repository without waiting for its schedule, choose Rescan now on the Repositories tab, or:

limacharlie cloudsec code rescan acme/payments

The rescan is accepted immediately and starts after a 10-minute window, so that several requests or pushes for the same repository become one scan. Check the result on the repository's row, not in the rescan response. For GitLab and Bitbucket, add --provider gitlab or --provider bitbucket.