Download Rules

Download rules control what package clients can fetch. Use them to quarantine vulnerable versions, enforce naming or age policies, or keep matching metadata out of client results.

At a glance

• Available for: local and remote repositories when the feature is included in your plan. Virtual repositories are not supported.
• Targets: packages or package versions.
• Actions: Block download denies matching requests; Hide package also removes matching content from metadata and direct requests.
• Conditions: names, dates, versions, and vulnerability scan results where supported.

The fields and operators shown in RepoFlow adapt to the selected repository and package type.

Choose a target and action, then combine conditions in the visual builder.

Use download rules

1. Open a local or remote repository and select Download Rules from its details.
2. Select Create Rule, then choose a package or version target.
3. Choose Block download or Hide package and add your conditions.
4. Review the readable rule summary, enable the rule, and save it.
5. Test the policy with a package client before relying on it in production.

Block versus hide

Use Block download when clients may discover an item but must not fetch it. Use Hide package when it should not appear in package metadata. Remote repositories cannot use hide mode with CVE conditions; use block mode instead.

Examples

Choose an example to see a complete rule. The JSON contains only the rule body; select the matching target and action when creating the rule.

Package policies

Match one package by its exact name.

Target: Package

{
  "conditions": {
    "field": "name",
    "operator": "EQUALS",
    "value": "left-pad"
  }
}

Version policies

Match specific versions of a package.

Target: Version

{
  "conditions": {
    "and": [
      {
        "field": "packageName",
        "operator": "EQUALS",
        "value": "axios"
      },
      {
        "field": "version",
        "operator": "IN",
        "value": [
          "1.6.0",
          "1.6.1"
        ]
      }
    ]
  }
}

Vulnerability policies

Match versions with a critical CVE or more than five high-severity CVEs.

Requires vulnerability scanning. Use block mode for CVE rules on remote repositories.

Target: Version

{
  "conditions": {
    "or": [
      {
        "field": "criticalCveCount",
        "operator": "GREATER_THAN",
        "value": 0
      },
      {
        "field": "highCveCount",
        "operator": "GREATER_THAN",
        "value": 5
      }
    ]
  }
}

Rule JSON reference

Download rule JSON has one top-level conditions object. A leaf condition uses field, operator, and value; groups can be nested with and, or, and not.

The reference below shows the complete baseline model. Actual support is repository-specific: ordered version comparisons vary by package type, some remote repositories do not expose creation dates, and CVE fields require vulnerability scanning.

Condition structure: use a leaf condition with field, operator, and value. Combine conditions recursively with and, or, or not.

Field	Type	Supported operators
name	string	EQUALS, NOT_EQUALS, IN, NOT_IN, MATCHES, NOT_MATCHES
creationDay	date	EQUALS, NOT_EQUALS, GREATER_THAN, LESS_THAN, OLDER_THAN_DAYS, NOT_OLDER_THAN_DAYS
lastDownloadedDay	date	EQUALS, NOT_EQUALS, GREATER_THAN, LESS_THAN, OLDER_THAN_DAYS, NOT_OLDER_THAN_DAYS

Example rule JSON

{
  "conditions": {
    "field": "name",
    "operator": "MATCHES",
    "value": "^@company/"
  }
}

Vulnerability behavior

When a rule uses CVE fields, configure what happens while a scan is missing or stale:

• wait_for_scan waits for a result before deciding.
• deny_while_scanning blocks the request until a result is ready.
• allow_while_scanning allows the request while scanning continues.

Use cveScanMaxAgeHours to decide when a previous result is too old to reuse.

API and self-hosting

Use the List Download Rules API to inspect saved policies and enforcement counts. Use the Create Download Rule API to add a policy; validate repository-specific fields and operators against the feature reference above.

For a self-hosted deployment, see Download Rules Configuration for limits and cache settings.