JFrog Xray Terraform Provider

The xray_watch resource allows you to create and manage Xray Watches. A Watch monitors specific resources (like repositories, builds, or projects) and applies security, license, or operational risk policies to them. When a policy violation is detected, notifications can be sent to specified recipients.

Key capabilities include:

• Monitoring various resource types: all-repos, repository, all-builds, build, all-projects, project, and gitRepository.
• Applying multiple policies of different types (security, license, operational_risk) to a single watch.
• Filtering resources using regex, mime-type, Ant patterns, or key-value properties.
• Specifying notification recipients via watch_recipients.

resource "xray_watch" "example" {
  name        = "example-watch"
  description = "A watch for a specific repository"
  active      = true
  project_key = "my-project"

  watch_resource {
    type       = "repository"
    bin_mgr_id = "default"
    name       = "my-repo"
    repo_type  = "local"
  }

  assigned_policy {
    name = "my-security-policy"
    type = "security"
  }

  watch_recipients = ["admin@example.com"]
}

An xray_security_policy is composed of one or more rule blocks. Each rule defines specific criteria that trigger a set of actions.

Common Criteria Types

• Severity: Use min_severity (e.g., "High") and fix_version_dependant (boolean) within a criteria block.
• CVSS Score: Use the cvss_range block with from and to (floats) to define a score range.
• SAST: Use the sast block with min_severity to define Static Application Security Testing thresholds.
• Malicious Packages: Set malicious_package = true within the criteria block to target malicious software.

Example: CVSS Range Rule

resource "xray_security_policy" "cvss_score" {
  name        = "test-security-policy-cvss"
  description = "Security policy description"
  type        = "security"
  project_key = "testproj"

  rule {
    name     = "rule-name-cvss"
    priority = 1

    criteria {
      cvss_range {
        from = 1.5
        to   = 5.3
      }
    }

    actions {
      mails = ["test@email.com"]
      fail_build = true
    }
  }
}

The paths_config block enables fine-grained control over retention periods and scanning for specific paths within a repository.

Pattern-based configuration (pattern):

• include (String, Required): The path pattern to include.
• exclude (String): The path pattern to exclude.
• index_new_artifacts (Boolean): If true, Xray scans newly added artifacts in the path (existing artifacts are not scanned).
• retention_in_days (Number): The retention period for artifacts in this specific path.

Fallback configuration (all_other_artifacts): If you use pattern blocks, you must define an all_other_artifacts block to set the retention period for any artifacts that do not match your defined patterns.

• index_new_artifacts (Boolean): Whether to scan newly added artifacts in the fallback path.
• retention_in_days (Number): The retention period for all other artifacts.

The watch_resource block defines what Xray is monitoring. You can define multiple watch_resource blocks within a single xray_watch to monitor different entities.

Supported Resource Types

• all-repos: Monitors all repositories.
• repository: Monitors specific repositories. Requires bin_mgr_id, name, and repo_type (local or remote).
• all-builds: Monitors all builds. Requires bin_mgr_id.
• build: Monitors specific builds. Requires bin_mgr_id and name.
• all-projects: Monitors all projects. Requires bin_mgr_id.
• project: Monitors specific projects. Requires name.
• gitRepository: Monitors Git repositories. Requires bin_mgr_id and name.

Filtering Options within watch_resource

Depending on the resource type, you can apply various filters:

• filter: Uses type (e.g., regex, mime-type) and value to filter artifacts.
• ant_filter: Uses include_patterns and exclude_patterns (Ant-style patterns) for builds or projects.
• path_ant_filter: Uses include_patterns and exclude_patterns for file paths within a repository.
• kv_filter: Uses type (e.g., property), key, and value to filter based on artifact properties.

resource "xray_watch" "repository-with-filters" {
  name        = "repo-watch"
  active      = true
  project_key = "testproj"

  # Example: Repository with mime-type filter
  watch_resource {
    type       = "repository"
    bin_mgr_id = "default"
    name       = "my-repo"
    repo_type  = "remote"

    filter {
      type  = "mime-type"
      value = "application/json"
    }
  }

  # Example: Repository with path Ant filter
  watch_resource {
    type       = "repository"
    bin_mgr_id = "default"
    name       = "my-repo-2"
    repo_type  = "local"

    path_ant_filter {
      exclude_patterns = ["**/*.md"]
      include_patterns = ["**/*.js"]
    }
  }

  # Example: Repository with property (KV) filter
  watch_resource {
    type       = "repository"
    bin_mgr_id = "default"
    name       = "my-repo-3"
    repo_type  = "local"

    kv_filter {
      type  = "property"
      key   = "artifact-property-name"
      value = "artifact-property-value"
    }
  }

  assigned_policy {
    name = "my-policy"
    type = "security"
  }
}

To use the Xray provider, declare it in your terraform block and configure the provider "xray" block with your Xray instance URL and authentication credentials. You can provide credentials via the access_token argument or through environment variables.

Provider Configuration Options:

• url: The URL of your Xray instance (e.g., artifactory.site.com/xray).
• access_token: Your Xray access token.
• skip_xray_version_check: (Optional) Boolean to skip the Xray version check. Defaults to false.

Environment Variables:

• JFROG_URL or XRAY_URL: Set the Xray URL.
• XRAY_ACCESS_TOKEN or JFROG_ACCESS_TOKEN: Set the access token.
• SKIP_XRAY_VERSION_CHECK: Set to true to skip the version check.

terraform {
  required_providers {
    xray = {
      source  = "jfrog/xray"
      version = "3.1.1"
    }
  }
}

provider "xray" {
  url          = "artifactory.site.com/xray"
  access_token = "abc..xy"
  
  // optional: Skip xray version check, default is false.
  // skip_xray_version_check = true
}