# Security Audit

Scan Docker images or filesystem for vulnerabilities, secrets, misconfigurations and license issues using Trivy.

## YAML Parameters

```typescript
interface YAMLParameters {
  /** Configuration of the scan target, enabled scanners, severities and failure policy. */
  scan: ScanYaml;
  type: "SECURITY_AUDIT";
  /** Unique identifier for the action within the pipeline. */
  action: string;
  /** Rules that suppress specific findings from the scan report. Each rule type is keyed by the finding category it applies to. */
  ignore?: IgnoreYaml;
  /** Specifies when the action should be executed. */
  trigger_time?: "ON_EVERY_EXECUTION" | "ON_SUCCESS" | "ON_FAILURE" | "ON_BACK_TO_SUCCESS" | "ON_WARNING" | "ON_WAIT_FOR_APPROVE" | "ON_TERMINATE";
  /** The list of variables for dynamic action execution. The action runs once for each value. */
  loop?: string[];
  /** Defines whether the action should be executed on each failure. Restricted to and required if the trigger_time is ON_FAILURE. */
  run_only_on_first_failure?: boolean;
  /** When set to true the action is disabled. By default it is set to false. */
  disabled?: boolean;
  /** The timeout in seconds. */
  timeout?: number;
  /** If set to true the execution will proceed, mark action as a warning and jump to the next action. Doesn't apply to deployment actions. */
  ignore_errors?: boolean;
  /** Delay time between auto retries in seconds. */
  retry_interval?: number;
  /** Number of retries if the action fails. */
  retry_count?: number;
  /** Defines whether the action should run in parallel with the next one. */
  run_next?: "WAIT_ON_SUCCESS" | "IN_SOFT_PARALLEL" | "IN_HARD_PARALLEL";
  /** The list of trigger conditions to meet so that the action can be triggered. */
  trigger_conditions?: TriggerConditionYaml[];
  /** The list of variables you can use in the action. */
  variables?: VariableYaml[];
}
```

## Type Definitions

```typescript
interface ScanYaml {
  /** Scan target type */
  type?: "IMAGE" | "FILESYSTEM";
  /** Image source specification */
  image?: ImageYaml;
  /** Filesystem path to scan. Defaults to the pipeline's root filesystem. */
  path?: string;
  /** Paths (files or directories) to skip during the scan. */
  skip_paths?: string[];
  /** Enabled Trivy scanners. */
  scanners?: string[];
  /** Severity levels that trigger reporting. */
  severities?: string[];
  /** When `true`, the action fails only when a vulnerability has a fix available. Default: `false`. */
  fail_only_on_fixable?: boolean;
}

interface IgnoreYaml {
  /** Rules suppressing vulnerability findings. Rule `id` must be a CVE identifier (for example `CVE-2023-45853`). */
  vulnerabilities?: IgnoreRuleYaml[];
  /** Rules suppressing misconfiguration findings. Rule `id` must be an AVD/rule identifier (for example `AVD-DS-0001`). */
  misconfigurations?: IgnoreRuleYaml[];
  /** Rules suppressing secret findings. Rule `id` must be a secret rule identifier (for example `generic-api-key`). */
  secrets?: IgnoreRuleYaml[];
  /** Rules suppressing license findings. Rule `id` must be an SPDX license identifier (for example `0BSD`). */
  licenses?: IgnoreRuleYaml[];
}

interface TriggerConditionYaml {
  /** The type of trigger condition */
  trigger_condition: "ALWAYS" | "ON_CHANGE" | "ON_CHANGE_AT_PATH" | "VAR_IS" | "VAR_IS_NOT" | "VAR_CONTAINS" | "VAR_NOT_CONTAINS" | "DATETIME" | "SUCCESS_PIPELINE" | "DAY" | "HOUR" | "OR" | "VAR_LESS_THAN" | "VAR_LESS_THAN_OR_EQUAL" | "VAR_GREATER_THAN" | "VAR_GREATER_THAN_OR_EQUAL" | "ACTION_STATUS_IS" | "ACTION_STATUS_IS_NOT" | "TRIGGERING_USER_IS" | "TRIGGERING_USER_IS_NOT" | "TRIGGERING_USER_IS_IN_GROUP" | "TRIGGERING_USER_IS_NOT_IN_GROUP";
  /** The value to compare the trigger variable against */
  trigger_variable_value?: string;
  /** The name of the variable to check in the trigger condition */
  trigger_variable_key?: string;
  /** The timezone for datetime trigger conditions (e.g., 'UTC', 'Europe/Warsaw') */
  timezone?: string;
  /** The hours when the datetime trigger should activate (0-23) */
  trigger_hours?: number[];
  /** The days when the datetime trigger should activate (1-7, where 1 is Monday) */
  trigger_days?: number[];
  /** The project name for cross-project pipeline triggers */
  project?: string;
  /** The pipeline name for cross-pipeline triggers */
  pipeline?: string;
  /** The email of the user who can trigger the pipeline */
  trigger_user?: string;
  /** The name of the group that can trigger the pipeline */
  trigger_group?: string;
  /** The file paths that must change to trigger the pipeline */
  trigger_condition_paths?: string[];
  /** The action status to check for action status triggers */
  trigger_status?: "SUCCESSFUL" | "FAILED" | "SKIPPED" | "SUPPRESSED";
  /** The name of the action to check status for */
  trigger_action_name?: string;
  /** The list of nested trigger conditions for OR/AND operators */
  trigger_operands?: TriggerConditionYaml[];
}

interface VariableYaml {
  /** The name of the variable */
  key: string;
  /** The value of the variable */
  value?: string;
  /** The type of the added variable */
  type?: "VAR" | "FILE" | "SSH_KEY" | "IOS_KEYCHAIN" | "IOS_PROVISION_PROFILES" | "SSH_PUBLIC_KEY" | "GPG_KEY";
  /** If set to true the variable value will be encrypted and hidden */
  encrypted?: boolean;
  /** The optional description of the variable */
  description?: string;
  /** Initial path for the variable */
  init_path?: string;
  /** Default value for the variable */
  defaults?: string;
  /** Specifies where to copy the file on each run. Set if type is FILE, SSH_KEY, IOS_KEYCHAIN, or IOS_PROVISION_PROFILES. */
  file_path?: string;
  /** File permission set on copy to a container on each run. Set if type is FILE, SSH_KEY, IOS_KEYCHAIN, or IOS_PROVISION_PROFILES. */
  file_chmod?: string;
  /** Set if type is FILE, SSH_KEY, IOS_KEYCHAIN, or IOS_PROVISION_PROFILES. If it's NONE, the variable can be used as a parameter in an action. For CONTAINER, the given key is additionally copied to an action container on each run */
  file_place?: "NONE" | "CONTAINER";
  /** Password for certificates */
  password?: string;
  /** Passphrase for encrypted SSH keys */
  passphrase?: string;
  /** Key identifier for iOS certificates, provisioning profiles, or GPG keys */
  key_identifier?: string;
  /** If set to true the variable value can be set by Buddy actions */
  settable?: string;
  /** If set to true the variable is disabled and will not be injected anywhere */
  disabled?: boolean;
  /** Encoding of the variable value. Use `b64` for binary files (certificates, images, compiled blobs) where the value is already base64-encoded. Omit or set to `text` for plain text files (JSON, XML, config) — the system will handle encoding automatically. Only applies to non-encrypted asset variables (FILE, SSH_KEY, SSH_PUBLIC_KEY, IOS_KEYCHAIN, IOS_PROVISION_PROFILES). */
  encoding?: "text" | "b64";
}

```

## YAML Examples

### Scan image produced by the previous action

```yaml
  - action: "Security audit"
    type: "SECURITY_AUDIT"
    scan:
      type: "IMAGE"
      image:
        image_location: "ACTION"
        from_action: "Build Docker image"

```

### Scan a public image from Docker Hub

```yaml
  - action: "Security audit"
    type: "SECURITY_AUDIT"
    scan:
      type: "IMAGE"
      image:
        docker_registry: "DOCKER_HUB"
        name: "alpine"
        tag: "3.18"
      scanners:
        - "VULNERABILITY"
      severities:
        - "CRITICAL"
        - "HIGH"

```

### Scan the pipeline's filesystem with default path

```yaml
  - action: "Security audit"
    type: "SECURITY_AUDIT"
    scan:
      type: "FILESYSTEM"
      scanners:
        - "VULNERABILITY"
        - "MISCONFIGURATION"
        - "SECRET"
      severities:
        - "CRITICAL"
        - "HIGH"
        - "MEDIUM"

```

### Scan an image from a private Docker Hub repository

```yaml
  - action: "Security audit"
    type: "SECURITY_AUDIT"
    scan:
      type: "IMAGE"
      image:
        image_location: "PRIVATE_REGISTRY"
        docker_registry: "DOCKER_HUB"
        integration: "docker-hub"
        name: "my-org/my-app"
        tag: "v1.2.3"
      scanners:
        - "VULNERABILITY"
        - "SECRET"
        - "MISCONFIGURATION"
      severities:
        - "CRITICAL"
        - "HIGH"
        - "MEDIUM"
        - "LOW"
      fail_only_on_fixable: true

```

### Scan an image from a private Docker Hub repository

```yaml
  - action: "Security audit"
    type: "SECURITY_AUDIT"
    scan:
      type: "IMAGE"
      image:
        image_location: "PRIVATE_REGISTRY"
        docker_registry: "DOCKER_HUB"
        integration: "docker-hub"
        name: "my-org/my-app"
        tag: "v1.2.3"
      scanners:
        - "VULNERABILITY"
        - "SECRET"
        - "MISCONFIGURATION"
      severities:
        - "CRITICAL"
        - "HIGH"
        - "MEDIUM"
        - "LOW"
      fail_only_on_fixable: true

```

### Scan filesystem with skipped directories

```yaml
  - action: "Security audit"
    type: "SECURITY_AUDIT"
    scan:
      type: "FILESYSTEM"
      path: "/buddy/app"
      skip_paths:
        - "vendor/"
        - "node_modules/"
        - "dist/"
      scanners:
        - "VULNERABILITY"
        - "SECRET"
      severities:
        - "CRITICAL"
        - "HIGH"

```

### Scan filesystem with ignore rules for all kinds

```yaml
  - action: "Security audit"
    type: "SECURITY_AUDIT"
    scan:
      type: "FILESYSTEM"
      scanners:
        - "VULNERABILITY"
        - "SECRET"
        - "MISCONFIGURATION"
        - "LICENSE"
      severities:
        - "CRITICAL"
        - "HIGH"
    ignore:
      vulnerabilities:
        - id: "CVE-2023-45853"
          paths:
          - "vendor/"
        statement: "No upstream fix available, accepted risk"
        expires_at: "2026-09-21"
      misconfigurations:
        - id: "AVD-DS-0001"
          statement: "Intentional configuration"
      secrets:
        - id: "generic-api-key"
          paths:
          - "tests/fixtures/"
        statement: "Test data, not a real secret"
      licenses:
        - id: "0BSD"
          statement: "Approved by legal"

```

### Scan image and report every finding regardless of fix availability

```yaml
  - action: "Security audit"
    type: "SECURITY_AUDIT"
    scan:
      type: "IMAGE"
      image:
        image_location: "ACTION"
        from_action: "Build Docker image"
      scanners:
        - "VULNERABILITY"
        - "SECRET"
        - "MISCONFIGURATION"
      severities:
        - "CRITICAL"
        - "HIGH"
        - "MEDIUM"
      fail_only_on_fixable: false

```

### Scan a public image from a custom registry

```yaml
  - action: "Security audit"
    type: "SECURITY_AUDIT"
    scan:
      type: "IMAGE"
      image:
        image_location: "PUBLIC_REGISTRY"
        docker_registry: "OTHER"
        registry: "myregistry.example.com"
        name: "my-app"
        tag: "v1.2.3"
      scanners:
        - "VULNERABILITY"
      severities:
        - "CRITICAL"
        - "HIGH"

```

### Scan a private image from a custom registry using basic authentication

```yaml
  - action: "Security audit"
    type: "SECURITY_AUDIT"
    scan:
      type: "IMAGE"
      image:
        image_location: "PRIVATE_REGISTRY"
        docker_registry: "OTHER"
        registry: "myregistry.example.com"
        login: "registry-user"
        password: "registry-password"
        name: "my-app"
        tag: "v1.2.3"
      scanners:
        - "VULNERABILITY"
      severities:
        - "CRITICAL"
        - "HIGH"

```


---
Original source: https://buddy.works/docs/yaml/yaml-actions/security-audit