# Policies

Policies define automated rules that evaluate SBOMs against security, compliance, and quality standards. When an SBOM is uploaded and policy evaluation is enabled, the platform checks each policy rule and reports violations — enabling organizations to enforce standards across products, environments, and CI/CD pipelines.

***

## Overview

A Policy consists of one or more **rules**, each with a **subject** (what to evaluate), an **operator** (how to compare), and a **value** (the threshold or target). Policies can be scoped to specific Products and Environments, and their results can be surfaced as PR comments, notifications, and ticket creation.

Policies serve three primary purposes:

* **Gate enforcement** — block releases that fail security thresholds (e.g., no critical vulnerabilities in production).
* **Compliance monitoring** — track adherence to regulatory standards (e.g., SBOM quality score above 80%).
* **Risk alerting** — notify teams when risk indicators exceed thresholds (e.g., EPSS score above 0.5).

## Architecture

```
Policy Engine
  ├── Policy
  │     ├── Rule 1: Subject + Operator + Value
  │     ├── Rule 2: Subject + Operator + Value
  │     └── Rule N: ...
  │
  ├── Evaluation Trigger
  │     ├── Automatic: on SBOM upload (when enabled in Settings)
  │     └── Manual: on-demand scan
  │
  └── Results
        ├── Pass / Fail per rule
        ├── Violation details (component, vulnerability, value)
        ├── PR comments (when enabled)
        ├── Notifications (Slack, Teams, Email)
        └── Ticket creation (Jira, Linear)
```

**Interactions:**

* **Environment Settings** — policies are evaluated per Environment when enabled.
* **Automation Rules** — automation executes before policy evaluation, so automation fixes may resolve potential violations.
* **Notifications** — policy failures trigger notifications based on configured integrations.
* **CI/CD** — policy results can be posted as PR comments and used to fail builds.

***

## Creating Policies

### Via Dashboard

1. Navigate to the **Policies** page in the main navigation.
2. Click **+ Create Policy**.
3. Enter a **Policy Name** — use a descriptive name that communicates the policy's purpose (e.g., `Production Vulnerability Gate`, `SBOM Quality Minimum`).
4. Add one or more **Rules** (see Rule Configuration below).
5. Click **Save**.

### Policy Scope

Policies can be applied at two levels:

| Scope                 | Behavior                                              |
| --------------------- | ----------------------------------------------------- |
| **Organization-wide** | Policy is evaluated for all Products and Environments |
| **Product-specific**  | Policy is applied only to selected Products           |

To assign a policy to specific Products:

1. Navigate to the Product's Environment page.
2. Click the **Settings** tab.
3. Under **Policies**, select the policies to apply.

Alternatively, from the Policy detail page, assign the policy to specific Product Environments.

***

## Rule Configuration

Each rule defines a condition that is evaluated against SBOM data.

### Rule Structure

| Field        | Description                                                                                |
| ------------ | ------------------------------------------------------------------------------------------ |
| **Subject**  | The data attribute to evaluate (e.g., vulnerability severity, license type, component age) |
| **Operator** | The comparison type (e.g., IS, IS\_NOT, LESS\_THAN, MORE\_THAN, EXISTS)                    |
| **Value**    | The threshold or target value                                                              |

### Subject Categories

#### Vulnerability Subjects

| Subject                | Description                           | Operators                     |
| ---------------------- | ------------------------------------- | ----------------------------- |
| Vulnerability Severity | CVSS severity level                   | IS, IS\_NOT                   |
| CVSS Score             | Numeric CVSS base score               | LESS\_THAN, MORE\_THAN, RANGE |
| EPSS Score             | Exploit prediction probability        | LESS\_THAN, MORE\_THAN, RANGE |
| KEV Status             | Whether in CISA KEV catalog           | IS, IS\_NOT                   |
| VEX Status             | Vulnerability disposition             | IS, IS\_NOT                   |
| Vulnerability Count    | Number of vulnerabilities by severity | LESS\_THAN, MORE\_THAN        |

#### Component Subjects

| Subject           | Description                               | Operators                     |
| ----------------- | ----------------------------------------- | ----------------------------- |
| Component Name    | Specific component name                   | IS, IS\_NOT, EXISTS           |
| Component Version | Component version string                  | IS, IS\_NOT                   |
| Component License | License expression                        | IS, IS\_NOT, EXISTS           |
| Component Type    | Component kind (library, framework, etc.) | IS, IS\_NOT                   |
| Health Score      | Component health score (0–100)            | LESS\_THAN, MORE\_THAN, RANGE |
| Support Level     | Component maintenance status              | IS, IS\_NOT                   |

#### SBOM Subjects

| Subject            | Description              | Operators              |
| ------------------ | ------------------------ | ---------------------- |
| SBOM Quality Score | Compliance quality score | LESS\_THAN, MORE\_THAN |
| Supplier           | SBOM supplier field      | EXISTS, NOT\_EXISTS    |
| Data License       | SBOM data license field  | IS, IS\_NOT, EXISTS    |

#### Custom Field Subjects

| Subject            | Description                | Operators                        |
| ------------------ | -------------------------- | -------------------------------- |
| Custom Text Field  | User-defined text field    | IS, IS\_NOT, EXISTS, NOT\_EXISTS |
| Custom Range Field | User-defined numeric field | LESS\_THAN, MORE\_THAN, RANGE    |

For custom field configuration, see [Vulnerability Custom Fields](https://docs.interlynk.io/administration/vulnerability-custom-fields).

### Example Rules

| Policy Purpose                  | Subject                | Operator   | Value     |
| ------------------------------- | ---------------------- | ---------- | --------- |
| Block critical vulnerabilities  | Vulnerability Severity | IS         | Critical  |
| Require minimum quality score   | SBOM Quality Score     | MORE\_THAN | 80        |
| Flag KEV-listed vulnerabilities | KEV Status             | IS         | True      |
| Block high-EPSS vulnerabilities | EPSS Score             | MORE\_THAN | 0.5       |
| Require supplier information    | Supplier               | EXISTS     | —         |
| Flag abandoned components       | Support Level          | IS         | Abandoned |
| Minimum health score            | Health Score           | LESS\_THAN | 30        |

***

## Applying Policies

### Automatic Evaluation

Policies are evaluated automatically on SBOM upload when the relevant settings are enabled:

1. Navigate to the Product's Environment **Settings** tab.
2. Ensure **Run SBOM Checks** is enabled (prerequisite for policy evaluation).
3. Assign policies to the Environment.

The policy evaluation runs as part of the SBOM processing pipeline, after automation rules and vulnerability scanning.

### Manual Evaluation

To run policy evaluation on demand:

1. Navigate to the Product and select a Version.
2. Click **...** (Actions) on the Version.
3. Select **Run Policy Scan**.

### CI/CD Integration

Policy results can be integrated into CI/CD workflows:

**Fail-the-build pattern:**

```bash
# Upload SBOM
pylynk upload --prod "my-backend-service" --env "production" --sbom sbom.cdx.json

# Check processing status (includes policy results)
pylynk status --prod "my-backend-service" --env "production" --ver "v1.2.0"
```

The `pylynk status` command returns the policy evaluation status. In CI/CD pipelines, check the exit code to determine whether to proceed or fail the build.

**PR comments:**

When **Enable PR Comments** is turned on in Environment Settings, policy results are automatically posted as comments on pull requests via the configured source control integration (GitHub, GitLab, Bitbucket).

***

## Reviewing Policy Results

### Version-Level Results

1. Navigate to the Product and select a Version.
2. Click the **Policy** tab.
3. The results display:

| Column          | Description                                                                     |
| --------------- | ------------------------------------------------------------------------------- |
| **Policy Name** | Name of the evaluated policy                                                    |
| **Status**      | Pass or Fail                                                                    |
| **Violations**  | Number of rule violations                                                       |
| **Details**     | Expandable list of specific violations with affected components/vulnerabilities |

### Policy Detail View

1. Navigate to the **Policies** page.
2. Click on a policy to view its detail page.
3. The detail page shows:
   * Policy rules and their configuration.
   * Evaluation history across Products and Environments.
   * Aggregated violation counts.

***

## Managing Policies

### Editing Policies

1. Navigate to the **Policies** page.
2. Click on the policy to edit.
3. Modify rules, add new rules, or remove existing ones.
4. Click **Save**.

### Disabling Policies

Policies can be disabled without deletion:

1. Navigate to the Product's Environment **Settings** tab.
2. Remove the policy from the Environment's policy list.

### Deleting Policies

1. Navigate to the **Policies** page.
2. Click **...** (Actions) on the policy row.
3. Select **Delete**.
4. Confirm the deletion.

{% hint style="warning" %}
Deleting a policy removes all historical evaluation results for that policy. Disable policies instead of deleting them if you need to retain evaluation history.
{% endhint %}

***

## Notification and Ticketing on Violations

### Notifications

Policy failures can trigger notifications through configured integrations:

* **Slack** — violation summary posted to configured channels.
* **Microsoft Teams** — violation summary posted to configured channels.
* **Email** — violation details sent to subscribed users.

Subscribe to policy notifications on the Product Environment page by clicking the **Bell** icon and selecting **Policies**.

### Automatic Ticket Creation

When ticketing integrations are configured (Jira, Linear), policy violations can automatically create tickets for remediation tracking. This links the violation to a trackable work item.

For integration setup, see [Administration: Integrations](https://docs.interlynk.io/administration/integrations).

***

## Permission Matrix

| Permission            | Admin | Operator | Viewer |
| --------------------- | :---: | :------: | :----: |
| View policies         |   ✓   |     ✓    |    ✓   |
| Edit policies         |   ✓   |     ✓    |    —   |
| Run policy scans      |   ✓   |     ✓    |    —   |
| Delete policies       |   ✓   |     ✓    |    —   |
| Edit product policies |   ✓   |     ✓    |    —   |

For full permission details, see [Role Management](https://docs.interlynk.io/administration/role-management).

***

## Security Warnings

{% hint style="warning" %}
**Deleting a policy removes all historical results.** Evaluation history is permanently lost. Disable policies by removing them from Environments instead of deleting them if you need to preserve history.
{% endhint %}

{% hint style="warning" %}
**Overly permissive policies create a false sense of security.** Regularly review policy rules to ensure thresholds match your organization's risk tolerance. A policy that allows critical vulnerabilities in production defeats its purpose.
{% endhint %}

{% hint style="warning" %}
**Policy evaluation requires vulnerability scanning.** If "Run Vulnerability Scan" is disabled, vulnerability-related policy rules will not have data to evaluate against and may produce incomplete results.
{% endhint %}

***

## Common Misconfigurations

| Issue                              | Symptom                                           | Fix                                                                                       |
| ---------------------------------- | ------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| No policies created                | No policy results on any Version                  | Create policies on the Policies page and assign them to Product Environments              |
| Policy not assigned to Environment | Policy exists but never evaluates                 | Assign the policy to the target Environment in Product Settings                           |
| Vulnerability scanning disabled    | Vulnerability-related rules produce no violations | Enable "Run Vulnerability Scan" in Environment Settings                                   |
| SBOM checks disabled               | Quality score rules cannot evaluate               | Enable "Run SBOM Checks" in Environment Settings                                          |
| Policy too broad                   | Excessive violations overwhelm the team           | Narrow rules — use specific severity levels, EPSS thresholds, or KEV-only targeting       |
| Policy too narrow                  | Critical issues not caught                        | Review rules to ensure they cover your minimum security requirements                      |
| PR comments not posting            | Policy results not visible on pull requests       | Enable "Enable PR Comments" in Environment Settings and verify source control integration |
| Policy results stale               | Results do not reflect current SBOM state         | Run a manual policy scan or re-upload the SBOM                                            |

***

## Recommended Best Practices

* **Start with a minimal production gate.** Create a policy that fails on critical vulnerabilities and KEV-listed issues. Expand coverage over time.
* **Differentiate policies by Environment.** Production should have stricter policies than development. Use separate policies or environment-specific assignments.
* **Combine CVSS with EPSS for prioritization.** A rule that triggers on `CVSS > 7.0 AND EPSS > 0.1` catches high-severity, likely-exploited vulnerabilities while reducing noise.
* **Use policies to enforce SBOM quality.** Add rules for minimum quality scores, required supplier information, and data license compliance.
* **Enable PR comments in CI/CD Environments.** This gives developers immediate feedback on policy violations before merge.
* **Review policies quarterly.** As your security posture matures, tighten thresholds and add new rule categories.
* **Name policies descriptively.** Use names like `Production Critical Gate` or `FDA Compliance Minimum` rather than `Policy 1`.
* **Avoid creating too many policies.** Consolidate related rules into a single policy to simplify management and reduce evaluation overhead.
* **Use Custom Fields in policy rules** to enforce organization-specific risk thresholds (e.g., fail if custom risk score > 80).
* **Document policy rationale.** Maintain internal documentation of why each policy exists and what risk it mitigates.