# LicensePolicy

A licence policy: which licence categories produce findings and at what severity, how unresolved licences and dependency scopes are treated.

A licence policy: which licence categories produce findings and at what severity, how unresolved licences and dependency scopes are treated, and per-project overrides. Two forms are valid. The repository file .vulnetix/license-policy.yaml, read by vulnetix license and scan --evaluate-licenses, keeps the policy fields at the top level with no metadata; this is what vulnetix license policy init writes. The config form puts the same fields under spec, with metadata. Absent sections inherit the defaults: unknown is warn, no scope is ignored, and only strong-copyleft (high) and unknown (medium) carry a severity.

| | |
|---|---|
| `apiVersion` | `vulnetix.com/v1` |
| `kind` | `LicensePolicy` |
| Group | [Scanners and gates](/platform-iac/kinds/catalogue.md#scanners-and-gates) |
| Status | **Validate only.** The server stores nothing for it: validate and plan check a document, and apply sends nothing. |
| Objects per tenant | many, keyed by `metadata.name` |
| Token and role | None. The server stores nothing for this kind; validating needs no credential. |
| Terraform resource | None: the server stores nothing for this kind |
| CLI | [`vulnetix config validate`](/platform-iac/cli/validate.md) reads it (CLI v3.157.0 and later); `plan` and `apply` note it and send nothing. |
| Pinned schema | [`v1.19.1/LicensePolicy.schema.json`](https://github.com/Vulnesis/config-schemas/releases/download/v1.19.1/LicensePolicy.schema.json) |
| Newest schema | [`latest/LicensePolicy.schema.json`](https://github.com/Vulnesis/config-schemas/releases/latest/download/LicensePolicy.schema.json) |
| First released in | [`v1.1.0`](https://github.com/Vulnesis/config-schemas/releases/tag/v1.1.0) |
| Print the built-in copy | `vulnetix config schema LicensePolicy` |

## Minimal

Only the fields the kind requires. From `examples/LicensePolicy/minimal.yaml`.

**YAML**

```yaml
# yaml-language-server: $schema=https://github.com/Vulnesis/config-schemas/releases/latest/download/LicensePolicy.schema.json
apiVersion: vulnetix.com/v1
kind: LicensePolicy
metadata:
  name: default
spec: {}
```

**HCL**

There is no Terraform resource. The server stores nothing for this kind, so there is nothing for Terraform to manage. The file stays in the repository; see [Which files are Platform IaC documents](/platform-iac/cli/validate.md#which-files-are-platform-iac-documents).

**CLI** (validates it)

```bash
vulnetix config validate -f - <<'EOF'
# yaml-language-server: $schema=https://github.com/Vulnesis/config-schemas/releases/latest/download/LicensePolicy.schema.json
apiVersion: vulnetix.com/v1
kind: LicensePolicy
metadata:
  name: default
spec: {}
EOF
```

## Advanced

Every field the kind supports, with a `when` expression where it takes one. From `examples/LicensePolicy/advanced.yaml`.

**YAML**

```yaml
# yaml-language-server: $schema=https://github.com/Vulnesis/config-schemas/releases/latest/download/LicensePolicy.schema.json
apiVersion: vulnetix.com/v1
kind: LicensePolicy
metadata:
  name: default
  labels:
    team: legal
  annotations:
    approved-by: https://tracker.example.com/LEGAL-88
spec:
  categories:
    strong-copyleft:
      - AGPL-3.0-only
      - AGPL-3.0-or-later
      - SSPL-1.0
    proprietary:
      - BUSL-1.1
  severity:
    permissive: none
    public-domain: none
    weak-copyleft: low
    strong-copyleft: critical
    proprietary: high
    unknown: medium
  unknown: fail
  scopes:
    development: ignore
    test: ignore
    optional: evaluate
  projects:
    docs-site:
      severity:
        strong-copyleft: low
      unknown: ignore
      scopes:
        dev: ignore
---
# The repository file form, .vulnetix/license-policy.yaml: the same fields at the top level, no metadata.
apiVersion: vulnetix.com/v1
kind: LicensePolicy
severity:
  strong-copyleft: high
  unknown: medium
unknown: warn
scopes:
  test: ignore
```

**HCL**

There is no Terraform resource. The server stores nothing for this kind, so there is nothing for Terraform to manage. The file stays in the repository; see [Which files are Platform IaC documents](/platform-iac/cli/validate.md#which-files-are-platform-iac-documents).

**CLI** (validates it)

```bash
vulnetix config validate -f - <<'EOF'
# yaml-language-server: $schema=https://github.com/Vulnesis/config-schemas/releases/latest/download/LicensePolicy.schema.json
apiVersion: vulnetix.com/v1
kind: LicensePolicy
metadata:
  name: default
  labels:
    team: legal
  annotations:
    approved-by: https://tracker.example.com/LEGAL-88
spec:
  categories:
    strong-copyleft:
      - AGPL-3.0-only
      - AGPL-3.0-or-later
      - SSPL-1.0
    proprietary:
      - BUSL-1.1
  severity:
    permissive: none
    public-domain: none
    weak-copyleft: low
    strong-copyleft: critical
    proprietary: high
    unknown: medium
  unknown: fail
  scopes:
    development: ignore
    test: ignore
    optional: evaluate
  projects:
    docs-site:
      severity:
        strong-copyleft: low
      unknown: ignore
      scopes:
        dev: ignore
---
# The repository file form, .vulnetix/license-policy.yaml: the same fields at the top level, no metadata.
apiVersion: vulnetix.com/v1
kind: LicensePolicy
severity:
  strong-copyleft: high
  unknown: medium
unknown: warn
scopes:
  test: ignore
EOF
```

## Fields

Paths use dots for nesting and `[]` for the items of a list. **Required** means required whenever the parent object is present. A default is what the server uses when the field is left out.

| Field | Type | Required | Default | Allowed values | Description |
|---|---|---|---|---|---|
| <span id="apiVersion"></span>`apiVersion` | string | yes |  | exactly `vulnetix.com/v1` | The document format version. Every kind in this release is vulnetix.com/v1. |
| <span id="kind"></span>`kind` | string | yes |  | exactly `LicensePolicy` | Always LicensePolicy. |
| <span id="metadata"></span>`metadata` | object | no |  | no other keys |  |
| <span id="metadata-name"></span>`metadata.name` | string | yes |  | pattern `^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$` | The object's name, unique per kind within a tenant. It is the natural key: plan, apply, export and the Terraform provider all address an object by kind and name. |
| <span id="metadata-org"></span>`metadata.org` | string | no |  | format `uuid` | The tenant (organization UUID) the document belongs to. When set, plan and apply refuse to run against any other tenant. |
| <span id="metadata-labels"></span>`metadata.labels` | object | no |  | map of string to string (length 0 to 256); keys match `^[a-z0-9]([a-z0-9._/-]{0,61}[a-z0-9])?$` | Free key/value labels. Stored with the object, never interpreted by the server. |
| <span id="metadata-annotations"></span>`metadata.annotations` | object | no |  | map of string to string (length 0 to 4096) | Free key/value notes for people and tools, such as a ticket link. |
| <span id="spec"></span>`spec` | object | no |  | no other keys |  |
| <span id="spec-categories"></span>`spec.categories` | object | no |  | map of string to array of string (each item: length 1 to any) | Reassign SPDX ids to a category, overriding the built-in classification. |
| <span id="spec-severity"></span>`spec.severity` | object | no |  | map of string to string (`none`, `low`, `medium`, `high`, `critical`) | The severity of a finding against each category. |
| <span id="spec-unknown"></span>`spec.unknown` | string | no | `warn` | `warn`, `fail`, `ignore` | What an unresolved licence does. warn reports it without failing; fail treats it as a violation; ignore drops it. |
| <span id="spec-scopes"></span>`spec.scopes` | object | no |  | map of string to string (`evaluate`, `ignore`) | How each dependency scope is treated, keyed by scope name in lower case (development, dev, test, optional). ignore skips the scope; a scope left out is evaluated. |
| <span id="spec-projects"></span>`spec.projects` | object | no |  | map of string to object | Overrides for one project, keyed by the --project label. |
| <span id="spec-projects-key"></span>`spec.projects.<key>` | object | no |  | no other keys |  |
| <span id="spec-projects-key-severity"></span>`spec.projects.<key>.severity` | object | no |  | map of string to string (`none`, `low`, `medium`, `high`, `critical`) | The severity of a finding against each category. |
| <span id="spec-projects-key-unknown"></span>`spec.projects.<key>.unknown` | string | no |  | `warn`, `fail`, `ignore` | What an unresolved licence does. warn reports it without failing; fail treats it as a violation; ignore drops it. |
| <span id="spec-projects-key-scopes"></span>`spec.projects.<key>.scopes` | object | no |  | map of string to string (`evaluate`, `ignore`) | How each dependency scope is treated, keyed by scope name in lower case (development, dev, test, optional). ignore skips the scope; a scope left out is evaluated. |
| <span id="categories"></span>`categories` | object | no |  | map of string to array of string (each item: length 1 to any) | Reassign SPDX ids to a category, overriding the built-in classification. |
| <span id="severity"></span>`severity` | object | no |  | map of string to string (`none`, `low`, `medium`, `high`, `critical`) | The severity of a finding against each category. |
| <span id="unknown"></span>`unknown` | string | no | `warn` | `warn`, `fail`, `ignore` | What an unresolved licence does. warn reports it without failing; fail treats it as a violation; ignore drops it. |
| <span id="scopes"></span>`scopes` | object | no |  | map of string to string (`evaluate`, `ignore`) | How each dependency scope is treated, keyed by scope name in lower case (development, dev, test, optional). ignore skips the scope; a scope left out is evaluated. |
| <span id="projects"></span>`projects` | object | no |  | map of string to object | Overrides for one project, keyed by the --project label. |
| <span id="projects-key"></span>`projects.<key>` | object | no |  | no other keys |  |
| <span id="projects-key-severity"></span>`projects.<key>.severity` | object | no |  | map of string to string (`none`, `low`, `medium`, `high`, `critical`) | The severity of a finding against each category. |
| <span id="projects-key-unknown"></span>`projects.<key>.unknown` | string | no |  | `warn`, `fail`, `ignore` | What an unresolved licence does. warn reports it without failing; fail treats it as a violation; ignore drops it. |
| <span id="projects-key-scopes"></span>`projects.<key>.scopes` | object | no |  | map of string to string (`evaluate`, `ignore`) | How each dependency scope is treated, keyed by scope name in lower case (development, dev, test, optional). ignore skips the scope; a scope left out is evaluated. |

## Rules

Conditions the schema enforces beyond each field's own type. `vulnetix config validate` and the engine's plan report a document that breaks one.

| On | Rule |
|---|---|
| `the document` | Exactly one of these holds: (1) The config form: `metadata` is required, `spec` is required, `categories` is not allowed, `severity` is not allowed, `unknown` is not allowed, `scopes` is not allowed and `projects` is not allowed; (2) The repository file form: `spec` is not allowed. |

## Applying this kind

- **Not stored.** The engine registers the kind so that validate and plan check a document. A plan that includes one shows the warning `not_stored`, and apply sends nothing for it.

## Where it takes effect

The server does not store this kind. `vulnetix license` and `vulnetix scan --evaluate-licenses` read the repository file `.vulnetix/license-policy.yaml` on the machine running the scan. The engine registers the kind only so that validate and plan check a document against the schema: a plan that includes one shows the warning `not_stored` instead of refusing the set as an unknown kind. Commit the policy to `.vulnetix/license-policy.yaml` in each repository.

## Terraform and OpenTofu

There is no Terraform resource. The server stores nothing for this kind, so there is nothing for Terraform to manage. The file stays in the repository; see [Which files are Platform IaC documents](/platform-iac/cli/validate.md#which-files-are-platform-iac-documents).

## More examples

`examples/LicensePolicy/config.yaml` from `Vulnesis/config-schemas`:

```yaml
# yaml-language-server: $schema=https://github.com/Vulnesis/config-schemas/releases/latest/download/LicensePolicy.schema.json
apiVersion: vulnetix.com/v1
kind: LicensePolicy
metadata:
  name: default
spec:
  severity:
    strong-copyleft: critical
    proprietary: high
  unknown: fail
  scopes:
    test: ignore
```

`examples/LicensePolicy/repo-file.yaml` from `Vulnesis/config-schemas`:

```yaml
# yaml-language-server: $schema=https://github.com/Vulnesis/config-schemas/releases/latest/download/LicensePolicy.schema.json
# What vulnetix license policy init writes to .vulnetix/license-policy.yaml.
apiVersion: vulnetix.com/v1
kind: LicensePolicy
categories:
  strong-copyleft:
    - AGPL-3.0-only
    - AGPL-3.0-or-later
    - SSPL-1.0
severity:
  permissive: none
  public-domain: none
  weak-copyleft: low
  strong-copyleft: high
  proprietary: high
  unknown: medium
unknown: warn
scopes:
  development: ignore
  dev: ignore
  test: ignore
  optional: ignore
projects:
  docs-site:
    severity:
      strong-copyleft: low
    unknown: ignore
```

Check a file with `vulnetix config validate -f <file>`. See [Validate documents](/platform-iac/cli/validate.md). In an editor, start the file with the [schema comment](/platform-iac/schemas/editors.md).
