From 9d227b7e3e8f0a7044de755673b4376d43eefba2 Mon Sep 17 00:00:00 2001 From: Lina Daher Date: Wed, 29 Jan 2025 12:50:11 +0000 Subject: [PATCH] GITBOOK-67: No subject --- SUMMARY.md | 24 +- .../features-and-capabilities/sca/README.md | 10 + .../sca/export-scan-results.md | 161 ++++---- .../sca/jfrog-security-research.md | 97 ++--- .../sdlc-policy-mangement/README.md | 130 ++++++- .../sdlc-policy-mangement/ignore-rules.md | 94 +++-- .../sdlc-policy-mangement/policies.md | 88 ----- products/xray/integrations/README.md | 12 - products/xray/integrations/jira.md | 346 ------------------ products/xray/integrations/webhooks.md | 20 - 10 files changed, 343 insertions(+), 639 deletions(-) delete mode 100644 products/xray/features-and-capabilities/sdlc-policy-mangement/policies.md delete mode 100644 products/xray/integrations/README.md delete mode 100644 products/xray/integrations/jira.md delete mode 100644 products/xray/integrations/webhooks.md diff --git a/SUMMARY.md b/SUMMARY.md index 10bb7af..4dd81b9 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -51,33 +51,29 @@ * [How to Utilize JFrog Catalog for Curation](products/curation/how-tos/how-to-utilize-jfrog-catalog-for-curation.md) * [Xray](products/xray/README.md) * [Supported Technologies](products/xray/supported-technologies.md) - * [Quick Start](products/xray/quick-start.md) - * [Configure](products/xray/configure.md) * [Features and Capabilities](products/xray/features-and-capabilities/README.md) * [SCA](products/xray/features-and-capabilities/sca/README.md) * [JFrog Security Research](products/xray/features-and-capabilities/sca/jfrog-security-research.md) * [Export Scan Results](products/xray/features-and-capabilities/sca/export-scan-results.md) - * [SDLC Policy Mangement](products/xray/features-and-capabilities/sdlc-policy-mangement/README.md) - * [Policies](products/xray/features-and-capabilities/sdlc-policy-mangement/policies.md) - * [Ignore Rules](products/xray/features-and-capabilities/sdlc-policy-mangement/ignore-rules.md) - * [Watches](products/xray/features-and-capabilities/sdlc-policy-mangement/watches.md) - * [Xray Reports](products/xray/features-and-capabilities/reports.md) * [Shift-Left Security with Xray Scanning in IDEs and CLI](products/xray/features-and-capabilities/shift-left-security-with-xray-scanning-in-ides-and-cli.md) + * [SDLC Policies in JFrog Xray](products/xray/features-and-capabilities/sdlc-policy-mangement/README.md) + * [Ignoring Violations in JFrog Xray: Understanding Ignore Rules](products/xray/features-and-capabilities/sdlc-policy-mangement/ignore-rules.md) + * [Watches](products/xray/features-and-capabilities/sdlc-policy-mangement/watches.md) * [Operational Risk Management](products/xray/features-and-capabilities/operational-risk-management.md) * [Malicious Package Detection](products/xray/features-and-capabilities/malicious-package-detection.md) - * [How-Tos](products/xray/how-tos/README.md) - * [How to Filter Out Your 1st Party Components in CycloneDX SBOM report](products/xray/how-tos/how-to-filter-1st-party-components.md) - * [How to Detect Malicious AI Models using Xray](products/xray/how-tos/how-to-detect-malicious-ai-models-using-xray.md) - * [Integrations](products/xray/integrations/README.md) - * [Webhooks](products/xray/integrations/webhooks.md) - * [Jira](products/xray/integrations/jira.md) - * [Admin](products/xray/xray-management/README.md) + * [Xray Reports](products/xray/features-and-capabilities/reports.md) + * [Quick Start](products/xray/quick-start.md) + * [Configure](products/xray/configure.md) + * [Manage Xray](products/xray/xray-management/README.md) * [Advanced Settings](products/xray/xray-management/advanced-settings.md) * [Custom Software Licenses](products/xray/xray-management/custom-licenses.md) * [Xray <--> Jfrog External DB Sync](products/xray/xray-management/db-sync.md) * [Set a Retention Period for Xray Indexed Resources](products/xray/xray-management/retention-period.md) * [System Monitoring](products/xray/xray-management/system-monitoring.md) * [TLS Certificates](products/xray/xray-management/tls-certificates.md) + * [How-Tos](products/xray/how-tos/README.md) + * [How to Filter Out Your 1st Party Components in CycloneDX SBOM report](products/xray/how-tos/how-to-filter-1st-party-components.md) + * [How to Detect Malicious AI Models using Xray](products/xray/how-tos/how-to-detect-malicious-ai-models-using-xray.md) * [JFrog Xray](products/xray/xray/README.md) * [Xray Concepts](products/xray/xray/xray-concepts.md) * [Advanced Security](products/advanced-security/README.md) diff --git a/products/xray/features-and-capabilities/sca/README.md b/products/xray/features-and-capabilities/sca/README.md index 3d838d0..82b4053 100644 --- a/products/xray/features-and-capabilities/sca/README.md +++ b/products/xray/features-and-capabilities/sca/README.md @@ -1,7 +1,17 @@ # SCA +Software Composition Analysis (SCA) identifies and manages open-source and third-party components within software applications. SCA solutions help organizations detect security vulnerabilities, license compliance issues, and operational risks associated with external dependencies. + +JFrog Xray is a **universal SCA solution** that integrates **natively with JFrog Artifactory** to provide deep visibility into the composition of software artifacts, ensuring security and compliance throughout the software development lifecycle. + **Key Capabilities:** * **Automated Dependency Scanning:** Analyzes all layers of software, including direct and transitive dependencies. * **Multi-Language Support:** Covers **Maven, npm, Docker, PyPI, NuGet, Go, and more**. * **Integration with JFrog Artifactory:** Seamless scanning of artifacts stored in repositories. + +Xray scans software components against its **continuously updated vulnerability database**, including: + +* **Public CVE databases** (National Vulnerability Database, MITRE) +* **JFrog Security Research Team’s enriched vulnerability insights** +* **Malicious package detection for compromised open-source libraries** diff --git a/products/xray/features-and-capabilities/sca/export-scan-results.md b/products/xray/features-and-capabilities/sca/export-scan-results.md index 034aa96..c7382a1 100644 --- a/products/xray/features-and-capabilities/sca/export-scan-results.md +++ b/products/xray/features-and-capabilities/sca/export-scan-results.md @@ -1,92 +1,129 @@ # Export Scan Results -Xray allows you to export your artifact scan results for multiple use cases including: +JFrog Xray allows you to **export artifact scan results** for various **security, compliance, and operational** use cases. This enables organizations to **analyze vulnerabilities, enforce policies, and generate detailed reports** for auditing and compliance. -* Security - * Vulnerabilities - * Secret detection (JFrog Advanced Security) - * Application misconfigurations (JFrog Advanced Security) -* Legal Compliance -* General SBOM -* Policy Violations -* Operational risk of software components +#### **Use Cases for Exporting Scan Results** +You can export scan results for multiple scenarios, including: +* **Security Analysis** – Identify vulnerabilities and security risks. +* **Secret Detection** _(Available in JFrog Advanced Security)_ – Detect sensitive data leaks. +* **Application Misconfigurations** _(Available in JFrog Advanced Security)_ – Identify security weaknesses. +* **Legal Compliance** – Review and manage open-source licenses. +* **SBOM (Software Bill of Materials)** – Gain visibility into software components and dependencies. +* **Policy Violations** – Export violations related to security, compliance, and operational policies. +* **Operational Risk** – Assess the **stability, maintenance, and lifecycle** of software components. -## How to Export Scan Result +*** -Press the \[...] Button at the scan result screen and press "Export Scan Data" and choose your export type. +### **How to Export Scan Results** -
+1. Navigate to the **scan result screen** in Xray. +2. Click the **\[...] (More Options) button**. +3. Select **"Export Scan Data"** and choose the desired **export type**. -## Security Export +*** -The Security Export Include the following fields about your artifact detected vulnerabilities: +### **Types of Scan Result Exports** -* CVE -* Severity -* JFrog Severity -* Component Physical Path -* Infected Component -* Infected Version -* Edited Time -* Applicability (For JFrog Advanced Security Users) +#### **1. Security Export** -## Legal Compliance Report +The **Security Export** report provides details about detected vulnerabilities in scanned artifacts. -The legal compliance report allows users to review their software components licenses - including local-file detected licenses and 3rd-party externally enriched licenses. +**Included Fields:** -the Supported fields for the legal compliance report are : +* **CVE ID** – Unique identifier for the vulnerability. +* **Severity** – The standard **CVSS-based severity rating**. +* **JFrog Research Severity** – Adjusted severity based on **JFrog’s advanced security research**. +* **Component Physical Path** – The exact location of the affected component. +* **Infected Component** – The specific package or library impacted. +* **Infected Version** – The version of the affected component. +* **Edited Time** – The timestamp of the latest scan result update. +* **Applicability** _(For JFrog Advanced Security Users)_ – Indicates whether the vulnerability is **actually exploitable** in real-world scenarios. -* Component Name -* Licenses -* License Links -* Package Type -* Component ID -* Package ID -* Version +*** +#### **2. Legal Compliance Report** +This report provides an overview of **software licenses** associated with your components, including **internally detected** and **externally enriched** licenses. -## Violations Report +**Included Fields:** -The Violations report allows you to export all policy violations associated with your artifact SCA scan . +* **Component Name** – Name of the software component. +* **Licenses** – Detected open-source licenses associated with the component. +* **License Links** – Links to legal references for each license. +* **Package Type** – The software package format (e.g., npm, Maven, PyPI). +* **Component ID** – A unique identifier for the component. +* **Package ID** – The ID of the package in the repository. +* **Version** – The specific version of the component. -The violations report fields are: +*** -* Violation Summary -* Severity -* Violation Type -* Watch Name (Policy Scope) -* Component Physical Path -* Component -* Created Date -* Policy which created the violation -* Applicability (For JFrog Advanced Security Users) +#### **3. Violations Report** -## SBOM Report +The **Violations Report** provides a detailed list of **policy violations** associated with the **SCA (Software Composition Analysis) scan** of an artifact. -SBOM is a readable inventory of software components and dependencies. The report will include SBOM data of your components, including unidentified components and open-source software. This enables you to: +**Included Fields:** -* Understand components and code dependencies. -* Gain visibility into open-source licenses for the components in use. -* Be aware of the end-of-life of components, and which components need to be updated. -* Identify vulnerable components or recently identified vulnerabilities. -* Enforce organizational compliance and policies. +✔ **Violation Summary** – A brief description of the policy violation.\ +✔ **Severity** – Risk level of the violation (e.g., Minor, Major, Critical).\ +✔ **Violation Type** – The category of violation (e.g., Security, License, Operational Risk).\ +✔ **Watch Name** – The policy scope applied to the violation.\ +✔ **Component Physical Path** – Location of the affected artifact.\ +✔ **Component** – The specific component that triggered the violation.\ +✔ **Created Date** – Timestamp of when the violation was detected.\ +✔ **Policy Triggered** – The policy rule that caused the violation.\ +✔ **Applicability** _(For JFrog Advanced Security Users)_ – Indicates whether the violation is **applicable in the current environment**. -### How it Works +*** -After performing an Xray scan, you can export the scan data as an SBOM report using one of the two supported SBOM formats: +#### **4. SBOM (Software Bill of Materials) Report** -* **SPDX**: Software Package Data Exchange (SPDX) is a standard format for communicating the components of software packages, including information about license copyrights. It includes several mechanisms that are especially useful for open-source software. - * Supported formats: - * tag:value - * JSON - * xlsx -* **CycloneDX**: CycloneDX is a lightweight SBOM specification designed specifically for software security requirements and related risk analysis. Starting with Xray version 3.67.x and above, the SBOM also includes VEX information, such as vulnerability details, exploitability, and detailed analysis. CycloneDX designed to be flexible, easily adaptable, with implementations for popular build systems. - * Supported formats: - * JSON - * XML +The **SBOM report** provides a **comprehensive inventory** of software components and dependencies. This report helps organizations:\ +✔ **Understand software composition** and dependencies.\ +✔ **Gain visibility into open-source licenses** and compliance requirements.\ +✔ **Identify outdated components** or software reaching end-of-life.\ +✔ **Detect vulnerable components** and recently disclosed CVEs.\ +✔ **Enforce software security policies** based on risk factors. + +**How to Export an SBOM Report** + +After an **Xray scan**, you can export an **SBOM report** using one of two industry-standard formats: + +#### **Supported SBOM Formats** + +**1. SPDX (Software Package Data Exchange)** + +SPDX is an industry-standard format for **communicating software components and license metadata**.\ +✔ Useful for **license management** and **compliance tracking**.\ +✔ Supports **open-source compliance reporting**. + +**SPDX Export Formats:** + +* **Tag:Value** +* **JSON** +* **XLSX (Excel format)** + +**2. CycloneDX** + +CycloneDX is a **lightweight SBOM format** designed for **software security and risk analysis**.\ +✔ Focuses on **security, vulnerability tracking, and exploitability**.\ +✔ As of **Xray version 3.67.x and above**, CycloneDX SBOMs also include **VEX (Vulnerability Exploitability Exchange)** data, providing: + +* **Vulnerability details** +* **Exploitability status** +* **Technical analysis of risks** + +**CycloneDX Export Formats:** + +* **JSON** +* **XML** + +*** + +#### **Conclusion** + +Exporting scan results in Xray allows organizations to **gain deep security insights**, **enforce compliance**, and **track vulnerabilities** effectively. By leveraging **Security, Compliance, Violations, and SBOM reports**, teams can improve **software supply chain security** and **regulatory compliance** while ensuring **operational resilience**. diff --git a/products/xray/features-and-capabilities/sca/jfrog-security-research.md b/products/xray/features-and-capabilities/sca/jfrog-security-research.md index a5ecfc6..85603a5 100644 --- a/products/xray/features-and-capabilities/sca/jfrog-security-research.md +++ b/products/xray/features-and-capabilities/sca/jfrog-security-research.md @@ -1,85 +1,52 @@ # JFrog Security Research -## CVE Research and Enrichment +### **CVE Research and Enrichment in JFrog Security** -**The Issue** +#### **The Challenge** -Software artifacts typically have a very high number of CVEs, in some cases, security reviews have found over 1K CVEs, but handling all of these CVEs is practically impossible. Usually, the common way of deciding which CVEs to resolve is based on CVSS scoring, as well as published technical information on the relevant security advisories. This can be very challenging and an insufficient method for understanding the actual risk raised by a vulnerability for the following reasons: +Modern software artifacts often contain **hundreds or even thousands of CVEs**, making it **impractical** to address every single one. Security teams typically rely on **CVSS scores** and **technical security advisories** to prioritize vulnerabilities, but this approach has several **limitations**: -* CVSS scoring provides very limited insight into the actual risk that the CVE poses. -* CVSS scoring does not contain a deep analysis on the chances of real-world exploitation. -* The values inserted into the CVSS formula do not represent either the common case or the preconditions that are needed for successful exploitation. -* The fixed weights of the CVSS formula do not reflect the actual risk in some cases. +* **Limited risk insight**: CVSS scores alone do not provide a clear picture of **real-world risk**. +* **No exploitability analysis**: They do not assess the **likelihood of exploitation** in actual attack scenarios. +* **Generic scoring formulas**: The fixed weights in CVSS calculations may not accurately reflect the **true risk** of a CVE. +* **Incomplete technical advisories**: Security bulletins often lack **detailed conditions for exploitation** or **alternative mitigation options** beyond upgrading the affected software. -In addition, the published technical information of CVEs in security advisories, is sometimes very limited. It would be very hard to understand these specific conditions that need to be met for the CVE to be applicable, as well as fixing solutions, which are not necessarily a software upgrade, but also code patches or any deployment or code mitigations. +Given these challenges, organizations struggle to determine **which vulnerabilities pose an actual threat** and how to **efficiently prioritize fixes**. -**The Solution** +*** -This is where JFrog Security CVE Research and Enrichment comes into play. JFrog security research and threat intelligence teams continuously review and analyze CVEs, existing and new ones, to determine if they are likely to be exploited by real-world attackers. Based on the analysis, the research team set a **JFrog Research Severity** score for CVEs, and provides detailed technical information on the specific conditions for the CVE to be applicable, as well as detailed fixing and mitigation options. +#### **The JFrog Solution: CVE Research and Enrichment** -CVEs analyzed by the JFrog security research team are determined by the following criteria: +JFrog’s **Security Research and Threat Intelligence teams** continuously analyze both **new and existing CVEs** to assess their **real-world exploitability** and impact. This analysis results in a **JFrog Research Severity Score**, which provides **deeper insights** into each CVE, including: -* The number of existing exploits (or creating an exploit is trivial). -* The number of documented real-world attacks. -* The potential impact of the exploitation. -* Having a high CVSS score. +✔ **Exploitability analysis** – How likely is the vulnerability to be weaponized?\ +✔ **Real-world attack data** – Has this CVE been used in documented cyberattacks?\ +✔ **Impact assessment** – What is the potential damage if exploited?\ +✔ **Severity refinement** – Adjustments based on deeper technical evaluation, beyond just the CVSS score. -After the deep analysis, CVEs are enriched with the following research information: +*** -* What is the vulnerable function and what is considered as a vulnerable call, that makes the exploitation possible and puts the software artifact at risk? -* What are the cases where the function is disabled or not compiled? -* What are the configurations that make the vulnerability hard to exploit? -* Affected software components and versions. -* Existing patches to fix the vulnerability with or without upgrading the component. -* Deployment or development mitigations to mitigate or eliminate the riskof the vulnerability. -* Which CPU architecture is relevant to the vulnerability if only specific ones are exploitable. +#### **How JFrog Research Enhances CVEs** -**What should you do with JFrog research enriched CVEs?** +After a thorough analysis, JFrog **enriches CVEs** with critical insights that help security teams make **informed decisions**: -CVEs with the highest JFrog security severity are the most likely to be used by real-world attackers. This means that you should put effort into fixing them as soon as possible. After fixing those CVEs, the risk of the software artifact being exploited by a CVE becomes much lower. +* **Vulnerable Function Identification** – Pinpoints **which function(s) are at risk** and what type of calls make them exploitable. +* **Non-Exploitable Scenarios** – Highlights **cases where the function is disabled or not compiled**, making the vulnerability ineffective. +* **Hard-to-Exploit Configurations** – Identifies settings or conditions that **reduce exploitability**. +* **Impacted Software Components & Versions** – Specifies **exact software versions** affected. +* **Fix and Mitigation Options** – Includes **patches, workarounds, and configuration changes** to reduce risk, even if upgrading is not an option. +* **Deployment-Level Mitigations** – Security strategies that can be applied **without modifying the source code**. +* **Relevant CPU Architectures** – Clarifies if a vulnerability **only affects specific processor architectures**. -To help you fix the issues, the JFrog security team provides you with detailed fix and mitigation options for the CVEs. In some cases, there are easier and harder ways to fix an issue. +*** -## View JFrog Research Enriched CVEs +#### **What Should You Do with JFrog Research-Enriched CVEs?** -You can access the CVE data in **Xray > Scans List**\ +**Prioritize the highest-risk vulnerabilities first.** CVEs with the **highest JFrog Security Severity Score** are **most likely** to be targeted by real-world attackers. These should be addressed **immediately** to **drastically lower the risk** of exploitation. +**Leverage JFrog’s Fix and Mitigation Options:** -
+* Some fixes are **quick and easy**, while others may require more effort. +* JFrog provides **alternative mitigation strategies**, including **patching, code fixes, configuration changes, or deployment-level protections**. -JFrog research enriched CVEs are indicated by an icon in the list.\ - - -
- -Once you click on the CVE, the CVE details are displayed in the right panel. The JFrog research enriched CVE will include the following additional details: - -### JFrog Research Severity - -The severity given by the JFrog security research team after the manual analysis by the team. - -### Remediation - -Displays fixed versions for the issue if any, or recommendations such as upgrading and mitigations. - -
- -### Research Summary - -A summary of the issue in the CVE based on JFrog's security analysis . - -
- -### Research Details - -A detailed description of the issue that provides more insights on the vulnerability, based on JFrog's security analysis. - -
- -### JFrog Research Severity Reasons - -The reasons behind the JFrog research severity. - -
- -\ +By utilizing **JFrog’s CVE Research and Enrichment**, organizations can **prioritize threats more effectively**, allocate resources efficiently, and **secure their software with confidence**. diff --git a/products/xray/features-and-capabilities/sdlc-policy-mangement/README.md b/products/xray/features-and-capabilities/sdlc-policy-mangement/README.md index 5018478..d48979b 100644 --- a/products/xray/features-and-capabilities/sdlc-policy-mangement/README.md +++ b/products/xray/features-and-capabilities/sdlc-policy-mangement/README.md @@ -1,7 +1,127 @@ -# SDLC Policy Mangement +--- +description: Enforcing Security and Compliance Throughout the Software Development Lifecyle +--- -**Key Capabilities:** +# SDLC Policies in JFrog Xray -* **Customizable Security Policies:** Create policies for **CVE severity, license types, and compliance standards**. -* **Automated Violations & Actions:** Set rules to **block downloads, fail builds, trigger alerts, or create Jira tickets**. -* **License Governance:** Manage open-source license policies and enforce compliance. +In modern software development, security and compliance must be integrated **at every stage** of the **Software Development Lifecycle (SDLC)**. JFrog Xray enables organizations to define **SDLC policies** that enforce security, legal compliance, and operational governance **from development to deployment**. These policies help prevent vulnerabilities, manage open-source licenses, and ensure software quality **before code reaches production**. + +*** + +### **Understanding SDLC Policies in Xray** + +SDLC policies in Xray are **configurable rules** that dictate **how software artifacts and dependencies** are assessed for security and compliance at different **SDLC phases**. + +Xray’s policies focus on:\ +✔ **Security** – Identifying vulnerabilities and threats in software components.\ +✔ **Compliance** – Enforcing open-source license policies and regulatory standards.\ +✔ **Operational Risk** – Managing outdated, deprecated, or unmaintained dependencies. + +These policies **automate decision-making** by triggering **violations, alerts, and preventive actions** whenever a policy rule is met. + +*** + +### **How SDLC Policies Work in Xray** + +#### **1. Define Policies** + +Organizations create policies based on **security, compliance, and risk requirements**. Policies include: + +* **Rules** – Conditions that trigger violations (e.g., CVE severity, banned licenses). +* **Actions** – Automated responses when a rule is met (e.g., block downloads, send alerts). + +#### **2. Apply Policies to Watches** + +A **Watch** is a security scope that monitors: + +* **Repositories** (e.g., scanning all artifacts in a Maven repository). +* **Builds** (e.g., ensuring CI/CD builds are free of vulnerabilities). +* **Release Bundles** (e.g., verifying security before software distribution). + +Policies are **linked to Watches** to enforce security at specific stages of the **SDLC**. + +#### **3. Automated Enforcement** + +When an artifact **matches a policy rule**, Xray automatically:\ +🚨 **Creates a violation** – Flags a security, compliance, or risk issue.\ +❌ **Blocks artifact downloads** – Prevents vulnerable components from entering production.\ +🔔 **Triggers alerts** – Notifies developers and security teams via email, Jira, or Slack.\ +🚀 **Fails builds** – Stops deployments that don’t meet security standards. + +*** + +### **Types of SDLC Policies in Xray** + +Xray provides three primary **policy types**, each serving a **different aspect of software security**: + +#### **1. Security Policies** + +Security policies help teams detect and **prevent vulnerabilities from entering software** by scanning artifacts and dependencies.\ +**Common Security Rules:**\ +✔ Block artifacts with **critical CVEs** (Common Vulnerabilities and Exposures).\ +✔ Prevent downloads of **malicious packages**.\ +✔ Require a **fix version** before deployment.\ +✔ Enforce **Exploitability Awareness** _(available in JFrog Advanced Security)_ – ensuring only exploitable vulnerabilities are flagged. + +**Example:**\ +A developer attempts to pull a **Docker image** with a **high-risk CVE** → Xray **blocks the download** and notifies security teams. + +*** + +#### **2. Compliance Policies** + +Compliance policies enforce **open-source licensing regulations** and **corporate software usage policies**.\ +**Common Compliance Rules:**\ +✔ **Banned License Enforcement** – Prevents the use of **GPL-licensed** components in proprietary software.\ +✔ **License Allowlist** – Restricts usage to **approved open-source licenses**.\ +✔ **Multi-license Handling** – Defines policies when a package has **multiple licenses**. + +**Example:**\ +A CI/CD pipeline builds a **Python package** that includes a **GPL-licensed dependency** → Xray **fails the build** to prevent a legal risk. + +*** + +#### **3. Operational Risk Policies** + +Operational risk policies **assess the reliability and maintainability** of software components.\ +**Common Operational Risk Rules:**\ +✔ **End-of-Life Detection** – Alerts when a dependency is **no longer maintained**.\ +✔ **Deprecated Package Monitoring** – Prevents the use of packages that are **no longer supported**.\ +✔ **Unmaintained Library Warnings** – Flags components with **no updates in over 12 months**. + +**Example:**\ +A team includes a **Java library** in a new project → Xray detects the **library is no longer maintained** and **suggests an alternative**. + +*** + +### **SDLC Stages Where Xray Policies Are Applied** + +SDLC policies are enforced **throughout the software lifecycle**: + +| **SDLC Phase** | **How Xray Applies Policies** | **Example Use Case** | +| ------------------------------------ | ---------------------------------------------------------- | --------------------------------------------------------------------------------- | +| **Builds** | Xray scans dependencies in Builds, blocking bad builds. | A **build fails** due to a **critical CVE** in an npm package. | +| **Artifact Storage (Repositories)** | Prevents risky artifacts from being stored in Artifactory. | A **Maven package with a banned license** is **blocked from upload**. | +| **Pre-Deployment (Release Bundles)** | Ensures software is secure before deployment. | A **Docker image** with a **vulnerable base layer** is **rejected from staging**. | +| **Production Monitoring** | Detects emerging security threats in deployed software. | A deployed component becomes vulnerable due to a **newly discovered CVE**. | + +*** + +### **Best Practices for Implementing SDLC Policies in Xray** + +\ +✔ **Automate CI/CD Enforcement** – Use Xray to **fail builds** that introduce security risks.\ +✔ **Define Policy Scopes Carefully** – Assign policies **to relevant repositories and builds**.\ +✔ **Enable Continuous Monitoring** – Keep policies **updated with the latest threat intelligence**.\ +✔ **Use Advanced Security Features** – Utilize **Exploitability Awareness and Applicability Scanning** _(available in JFrog Advanced Security)_ to **reduce false positives**. + +*** + +### **Conclusion** + +JFrog Xray’s SDLC policies provide a **proactive and automated approach** to **securing software** throughout the **development lifecycle**. By enforcing **security, compliance, and operational risk policies**, Xray ensures that **only safe and compliant software components** make it to **production.** + +\ + + +O diff --git a/products/xray/features-and-capabilities/sdlc-policy-mangement/ignore-rules.md b/products/xray/features-and-capabilities/sdlc-policy-mangement/ignore-rules.md index a8e7d44..2cc6317 100644 --- a/products/xray/features-and-capabilities/sdlc-policy-mangement/ignore-rules.md +++ b/products/xray/features-and-capabilities/sdlc-policy-mangement/ignore-rules.md @@ -1,50 +1,90 @@ -# Ignore Rules +# Ignoring Violations in JFrog Xray: Understanding Ignore Rules -> #### Note -> -> This feature is available with Artifactory version 7.10.5 and above. +In security and compliance management, **not all violations require immediate action**. Some vulnerabilities or policy violations may be **low risk**, **false positives**, or **already mitigated** through alternative security controls. -In some cases, when violations are detected, as security or legal personnel, you would like to accept or whitelist some of these violations. This could be for different reasons, such as: +JFrog Xray provides **Ignore Rules**, a feature that allows teams to **temporarily or permanently** suppress specific violations. This ensures that development teams can **focus on critical issues** while maintaining compliance and security standards. -* Although the security vulnerability is real, you have ways to protect against it (such as a WAF configuration). -* The conditions needed for this vulnerability to happen are not met in the specific case. -* As an organization, you are aware of the violation, but you would still like to release the product. -* The violation is not a showstopper, and you would like to deal with it in future versions. -* The violation is a false positive. -* The violation is valid, but you need more time to deal with it. Time based ignore enables you to silence the violation for a period of time. Once that period expires, the Ignore Rule will be deleted automatically, and if the violation occurs again it will not be ignored moving forward. +*** -In such cases, the ignore violations feature, enables you to have granular control on the violations that should be ignored. Xray allows you to define the scope of the ignore rule on the vulnerability, component, artifact, watch level, and more. Thus, giving you the flexibility and control needed to apply the ignore rule. +### **What Are Ignore Rules in Xray?** +Ignore Rules are **configurable exceptions** that allow users to **suppress violations** under certain conditions. These rules prevent violations from **blocking builds, failing deployments, or triggering alerts**, while still keeping them **logged for reference**. +Ignoring a violation **does not remove it from the database**—it simply **hides the violation from triggering alerts and enforcement actions** for a defined period. -### Ignore a Violation +#### **Why Use Ignore Rules?** -Follow these steps to create an **Ignore Rule** for a violation. When creating an ignore rule, the ignore rule is applied to the specific violation and all future violations that meet the ignore rule criteria. For a number of examples on when you might want to ignore violations, see [Ignore Violations Examples](https://jfrog.com/help/internal/api/webapp/print/d78555a2-5bbe-41b2-bf4c-9749412b1e26#topic-tL0gYBJ7L7hTW_px8sD8lw). +✔ **Reduce Noise** – Suppress **non-actionable** vulnerabilities and violations.\ +✔ **Improve Efficiency** – Allow teams to **focus on high-risk issues**.\ +✔ **Avoid False Positives** – Ignore vulnerabilities **that do not apply** to the specific environment.\ +✔ **Mitigated Vulnerabilities** – Suppress CVEs that are **already patched** via **configurations, network controls, or runtime mitigations**. -1. Select the required Watch and click the **Violations** tab. +*** - +### **How Ignore Rules Work** -
+Ignore Rules can be applied to: -You can also view violations for an Artifact, Build, or Release Bundle by selecting the Violations tab in a Package, or in the specific Artifact, Build, or Release Bundle. You can filter to see only ignored violations. +* **Specific CVEs** – Ignore a vulnerability affecting a component. +* **Components or Artifacts** – Suppress violations on a package or artifact. +* **Policy Violations** – Ignore a violation triggered by security, compliance, or operational policies. +* **Watches and Scopes** – Apply the ignore rule to a specific **repository, build, or release bundle**. -\ +Ignored violations remain **visible in audit logs** but **do not trigger alerts, block actions, or impact CI/CD workflows**. +*** -
+### **Types of Ignore Rules in Xray** -From the **Violations** list, hover over the required violation in the list and click ![image2020-10-26\_23-19-44.png](data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABQAAAASCAYAAABb0P4QAAACKUlEQVQ4Ea2U7U/TUBTG+bM3TcQPWxWDhGmUF41M/aDElyVDE5QY/WJkW7c1HWMYyAqDdVAmK8O19/btMefOGbpukw98uGl67j2/e57znHbKtm1c55q6ThixrgR0uQvO+JWUTAQ6jMNlLsotGc3OIQIe/Bc6EshsjsABjK6BJ5UUEvk4koUYvjQ+iws87o0FR4Au89C+aCO79xaJfAxr9QwopneaeKDcQaosQWnJoEsd5kTAISAd2NA+IpmP4fVOGkb3BP5fmbRHlSmtAlIlCfOlJBodLQINATljWFTmUDVUIXnYiD7UR8CB5+oSvje+wed+qMoQkBJeVJZRO6nCYS64zUEO0zh43EfVqKDe3oPvBHi59RRlvSCqvjx6ISDJy+ys4uv+hkg66jQg65ui2uJxDpIcR8vUhcx7xWkcnh1ExikEpB7lmz+woi6I3pm/O3io3EW6uoTZ0m1hDF16cKZhviihZ/VCciODzWyGi945kvJNNM0jIee8ZyJdWxYwagP17/3uKjK7b/4ZNlYybdDwZuvvsLK9gMAJwBgTiWQQLXJ+pjCN064RkRupkAJUZc+yMCPfgqznREX9OIfHXaQUCZ+0NWESxYdXqIeDTZK2/0tDcvMGasaWMIVir2pp0V+ahsHZ4edIIB2iMfl5uo1ELo517QMW1Tk8Ux/DsiwxTsOgwftYYB/q4dhs4ZF6H+v1rBgX6ukgedRzIpASyAj6Gib9EC6D/wAoHEqSE0N9rgAAAABJRU5ErkJggg==) **Ignore Violation**, located on the rightmost side of the line. +#### **1. Temporary Ignore** _(Set Expiration Date)_ -The **Create Vulnerability Ignore Rule** dialog box appears. +**Use Case:** When a **fix is planned** for a later release. - +✔ Suppresses violations for a **defined period** (e.g., **30 days**).\ +✔ The violation **automatically reactivates** after the expiration date.\ +✔ Useful for vulnerabilities that are **not currently exploitable** but will be addressed in a future update. -
+**Example:**\ +A development team is aware of a **CVE in a library**, but a **patched version will be released in 2 weeks**. They apply an **ignore rule for 14 days** to prevent unnecessary alerts. -> When selecting the ignore criteria, take note of the combinations you choose. Some combinations such as selecting everything as **Any** is not allowed as it will ignore all future violations (in the watch or in the system). -> -> The Ignore Rules REST API allows you to choose more scopes for the Ignore Rule as well as more options in each scope. +*** +#### **2. Permanent Ignore** _(No Expiration)_ + **Use Case:** When a **vulnerability is not applicable** or is already mitigated. + +✔ **Permanently suppresses** a violation.\ +✔ Useful when a **CVE does not affect the actual usage** of the component.\ +✔ Can be **manually removed** later if needed. + +**Example:**\ +A security vulnerability **only affects a deprecated function** in a library that the team **does not use**. Since the function is never called in production, the violation is **ignored permanently**. + +*** + +#### **3. Ignore Based on Scope (Repository, Build, Release Bundle)** + +**Use Case:** When a violation should be ignored **only in a specific context**. + +✔ Allows ignoring violations for a **specific repository, project, or build**.\ +✔ Prevents unnecessary enforcement actions in **low-risk environments** (e.g., dev/staging).\ +✔ Ensures that the **same violation is still enforced elsewhere** (e.g., in production). + +**Example:**\ +A vulnerability is detected in a **staging environment**, but **does not exist in production**. The team applies an ignore rule **only for the staging repository**, ensuring security policies remain strict in production. + +*** + +### **Best Practices for Using Ignore Rules in Xray** + +✔ **Set Expiration Dates for Temporary Ignores** – Ensure violations are **reevaluated periodically**.\ +✔ **Document Ignore Reasons** – Maintain transparency for **security audits and compliance**.\ +✔ **Use Scope-Based Ignores** – Avoid **suppressing violations globally** unless necessary.\ +✔ **Review Ignored Violations Regularly** – Periodically check **which vulnerabilities are ignored** and **reassess risks**. + +*** + +### **Conclusion** + +Xray’s **Ignore Rules** provide a **flexible way to manage security and compliance violations** without compromising software security. By allowing teams to **temporarily or permanently suppress violations**, Xray helps reduce noise, streamline workflows, and focus on **genuinely critical threats**. diff --git a/products/xray/features-and-capabilities/sdlc-policy-mangement/policies.md b/products/xray/features-and-capabilities/sdlc-policy-mangement/policies.md deleted file mode 100644 index 6e38576..0000000 --- a/products/xray/features-and-capabilities/sdlc-policy-mangement/policies.md +++ /dev/null @@ -1,88 +0,0 @@ -# Policies - -## Create an Xray Policy - -Creating an Xray Policy involves the following primary steps: - -1. In the **Administration** module, select **Watches & Policies** and from the **Policies** tab click **New Policy**. -2. Provide a name for the Policy. -3. Select the **Policy Type**; **Security**, **License**, or **Operational Risk**. For more information, see [Trigger Violations Using Xray Policy Rules](https://jfrog.com/help/r/6nte66fuu2ZQMB2dfriysg/6HGKZw6F3lnul8K12To_IQ) - -
-4. **Click Next**. - - The **Policy Rules List** appears. -5. Define the rules and actions depending on what you have selected. The various options are outlined in [Trigger Violations Using Xray Policy Rules](https://jfrog.com/help/r/6nte66fuu2ZQMB2dfriysg/6HGKZw6F3lnul8K12To_IQ) and [Policy Violation Automatic Actions](https://jfrog.com/help/r/6nte66fuu2ZQMB2dfriysg/ytBDSmiGVVseDRMOLK0qtQ). - -
- -
- - - -6. Click **Next**. - - The **Apply on Scope** section appears -7. Select the Watch or multiple Watches that contain the resources the Policy rules will apply to. - -
- -8. Click **Save Policy** to complete the creation. - -## Trigger Violations Using Xray Policy Rules - -Policies contain user-defined rules allowing you to trigger violations for specific vulnerabilities or license breaches by setting a license or security criteria, with a corresponding set of automatic actions according to your needs. Rules are processed according to the ascending order in which they are placed in the Rules list on the Policy. If a rule is met, the subsequent rules in the list will not be applied. - -Xray supports the following policy types: - -#### Security Rules - -A Security Rule allows you to create a set of rules around security vulnerabilities. These are the possible criteria: - -* **CVEs**: Create a rule to generate violations on CVEs by the following: - * **Minimal Severity** (Minor, Major, Critical, All): The minimal security vulnerability severity as it is in the JFrog vulnerabilities database. If the artifact or build contains a vulnerability with the selected severity or higher, the rule will meet the criteria, the automatic actions will be executed, and the policy will stop processing. - * **CVSS Score** (1-10): The CVSS score range to apply to the rule. This is used for a fine-grained control, rather than using the predefined severities. The score range is based on CVSS v3 scoring, and CVSS v2 score is CVSS v3 score is not available. - * **CVE IDs**: Create policy rules for specific vulnerability IDs that you input. You can add multiple vulnerability IDs up to 100, separated by ",". CVEs and Xray IDs are supported. - * **Except if a Fix Version is available**: Xray will not generate violations for issues that do not contain a fixed version. If a fixed version is available later, the violation will be generated. - * **Skip if not applicable CVEs (JFrog Advanced Security only)**: If The CVE is not applicable as defined by a Contextual Analysis scan, the rule will not be applied. -* **Malicious Packages:**Create a rule that generates violations for detected malicious packages. -* **Exposures:** Create a rule to generate violations for detected Secrets, Applications, Services and IaC misconfigurations. -* **Package Version:** Xray will generate violations for the specific packages defined in this Policy. Provide the package type and name, and versions. You can either select all versions of the package or custom versions. Custom versions allow you to add specific package versions, or include a range. - -#### License Rules - -A license Rule allows you to create a set of rules around license compliance. There are three possible criteria: - -* **Allowed Licenses**: Specifies an Allow List of OSS licenses that **may** be attached to a component. If a component has an OSS license outside the specified Allow List, The rule will meet the criteria, a violation will be generated, automatic actions will be executed, and the policy will stop processing. -* **Banned Licenses**: Specifies a Block List of OSS licenses that **may not** be attached to a component. If a component has any of the OSS licenses specified, The rule will meet the criteria, a violation will be generated, automatic actions will be executed, and the policy will stop processing. -* **Multiple license permissive approach:** A violation will not be generated if at least one license is valid in cases where multiple licenses were detected on the component. - -## Policy Violation Automatic Actions - -An action determines the automatic response to a detected Policy violation. You can define one or more action within each Policy Rule. Actions include the following: - -* **Generate Violation (Minor, Major, Critical)**: The severity of the violations that is generated if the criteria are met. -* **Notify Email:** This action lets you specify email addresses to which Xray should send an email message about a violation when one is triggered. For this to work, you need to have a mail server configured in Xray. -* **Notify Watch's Recipients:** This action lets you send an email to all the watch recipients about a violation when triggered. -* **Notify Deployer:** This action lets you send an email to the user who deployed the component about a violation when triggered. -* **Create Jira Ticket**: This action enables the Jira ticket creation in the Policy rules -* **Trigger Webhook:** This action lets you specify webhooks you have configured in Xray that should be invoked when a violation is triggered (See payload below). -* **Block Download:** This action lets you specify that artifacts should be blocked for download and allows you to select one of these options: - * Block Download: When set, Artifactory will block the download of artifacts that meet the Artifact Filter and Severity Filter specifications for this watch. - * Block Unscanned: When set, Artifactory will block download of artifacts that meet the Artifact Filter specifications for this watch, but have not been scanned yet or the Xray data has been removed due to a retention policy. For more information on Xray Data Retention, see [Indexing Xray Resources](https://jfrog.com/help/r/6nte66fuu2ZQMB2dfriysg/QkeI5aDvqoggEGUdFO49fw). -* **Block Release Bundle distribution:** This action lets you specify that Release Bundles should be blocked for download if they meet the policy criteria rule. -* **Fail Build:** This action lets you specify that if a CI server requests a build to be scanned, and the Watch triggers a violation, Xray will respond with an indication that the build job should fail. - - This action is only available if the Watch is defined with Builds as the target type. - - * **Grace Period**: There are many cases where you do not want to fail the first build, for example, some violations are not showstoppers, and you would like to look into them later without stopping the build creation. You can set a grace period for a number of days that you define according to your needs. During the grace period you define, the build will not fail and all violations are ignored during this period. An automatic Ignore Ruleis created for the grace period with the following criteria: - - * On the specific vulnerability/license - * On the specific component - * On any version of the specific build - * On the specific Policy - * On the specific Watch - - Once the grace period ends, the Ignore Rule is deleted, and if the build contains violations, those violations are created and the build will fail.\ - - diff --git a/products/xray/integrations/README.md b/products/xray/integrations/README.md deleted file mode 100644 index 4671e1c..0000000 --- a/products/xray/integrations/README.md +++ /dev/null @@ -1,12 +0,0 @@ -# Xray Integrations - - -## Supported Xray Integrations - - -| **#** | **Task** | **Description** | **For more information, see...** | -|-------|--------------------------------------------|-------------------------------------------------------------------------------------------------------|----------------------------------------------------| -| 1 | IDE | View information on how to configure integration with the JFrog Eclipse IDE Plugin, the JFrog IntelliJ IDEA plugin, and the JFrog Visual Studio Extension. | IDE Integration | -| 2 | Jira | Configure integration with Atlassian Jira for creating tickets based on Xray-identified security threats and violations. | Jira Integration | -| 3 | CI/CD Tools | Integrate Xray with your organization's CI/CD pipeline and learn how to fully automate the process. | CI/CD Integration | -| 4 | Webhook | Integrate Xray with your organization's CI/CD pipeline and learn how to fully automate the process. | Webhook Integration | \ No newline at end of file diff --git a/products/xray/integrations/jira.md b/products/xray/integrations/jira.md deleted file mode 100644 index a8eaff5..0000000 --- a/products/xray/integrations/jira.md +++ /dev/null @@ -1,346 +0,0 @@ -# Jira Integration - - - -With Xray's integration into Atlassian's Jira Software, you can manually or automatically create Jira tickets based on security threats identified by Xray. Once set up, policy violations are converted to Jira tickets. This allows the development teams to pinpoint the violations, prioritize them effectively, and take swift action to resolve them. - -## **Prerequisites** - -As a Jira admin, you must have the following information: - -> #### Note -> -> You must have Jira Admin permissions to be able to connect Jira to Xray. For the Jira-related steps, refer to [Atlassian Jira Documentation ](https://confluence.atlassian.com/jira) - - - -1. The supported authentication type should be one of OAuth1, OAuth2, or Basic Authentication. -2. User credentials depend on the authentication type. -3. Jira Project Name. -4. Issue type (bug, security, escalation, etc.). -5. Jira labels (optional). -6. Custom Field Mapping (optional). - -## Setup Jira Integration - -The setup process for Xray Jira Integration involves four crucial stages that generate tickets based on policy violations: - -### Connect to Jira Account - -Connect Jira to Xray through the Xray interface using one of the supported authentication methods. Navigate to **Administration > Xray > Settings > Integration** - -#### JFrog Cloud New Interface (Beta) - -On the taskbar, click (Platform Configurations), and select **Xray Settings > Integrations**. To learn more, click here. - -Xray supported authentication methods: - - - -| | Xray Self Hosted | Xray Cloud | -| ---------------------------------------------------------------------------------------- | ------------------------------------------- | ------------------------------------------- | -| **Jira Self-Managed (Jira Server / Data Center before Jira version 8.22.0)** | | | -| **Jira Self-Managed (Jira Server / Jira Data Center with or after Jira version 8.22.0)** | | | -| **Jira Cloud** | | | - -Follow the steps depending on the chosen authentication method. - -#### **When to use basic authentication?** - -[Basic authentication](https://en.wikipedia.org/wiki/Basic_access_authentication) provides a simple mechanism to do authentication when experimenting with the REST API, writing a personal script, or for use by a bot. However, as basic authentication repeatedly sends the username and password on each request, which could be cached in the web browser, it is not the most secure method of authentication we support. - -We recommend you use [OAuth](https://developer.atlassian.com/server/jira/platform/oauth/) over basic authentication for most cases. OAuth requires more work to implement, but it uses a token-based workflow that is much more secure. - -#### **Connect Jira to Xray Using OAuth1** - -#### Note - -This method is supported only for Self Managed Jira instances. - -1. Create a public key to input in Jira: - - For more information, see [https://developer.atlassian.com/server/jira/platform/oauth/#create-an-application-link](https://developer.atlassian.com/server/jira/platform/oauth/#create-an-application-link) (Step 1, Create Application link). -2. Copy your Jira URL into the dedicated box and click **Generate Key**. -3. In Atlassian: Copy and input the generated Key into your Jira "Link application" - Public Key. Your integration is ready for testing. -4. Click **Next**. - - A validation window will open with Jira validation that you need to allow to finish integration. If the window is not showing this message, go back to step 1. - - If the window does not appear, check your pop-up blocker settings, and then again try clicking on the Click here hyperlink shown in a modal window. -5. After approving the connection, click Test **Integration**. If everything is correct, the **Finish Step** appears. You are advised to click **Next** to complete the Integration by creating a profile. - -#### **Connect Jira Cloud to Xray using OAuth2** - -1. In your Jira account configure the Client and Secret ID. - - For more information, see [https://developer.atlassian.com/cloud/jira/platform/oauth-2-3lo-apps/](https://developer.atlassian.com/cloud/jira/platform/oauth-2-3lo-apps/) -2. In Atlassian: When you are required to input your **Scope Permissions**, use the following list of permissions: - - ``` - read:issue-type:jira - read:issue-type.property:jira - read:project:jira - read:project.property:jira - read:user:jira - read:application-role:jira - read:avatar:jira - read:group:jira - read:issue-type-hierarchy:jira - read:project-category:jira - read:project-version:jira - read:project.component:jira - read:field:jira - read:field-configuration:jira - read:issue-meta:jira - write:issue:jira - write:comment:jira - write:comment.property:jira - write:attachment:jira - read:issue:jira - read:label:jira - read:issue-security-level:jira - read:issue.vote:jira - read:issue.changelog:jira - read:status:jira - read:comment:jira - read:comment.property:jira - read:project-role:jira - ``` -3. In Atlassian: When inputting your **Callback URL**, use the **Copy Callback URL** in the Xray Jira wizard. -4. From the Xray Jira wizard, copy the generated Client ID and Secret to the related boxes and click **Next**. - - A validation window appears with Jira validation -5. Select the desired Atlassian account in the **Authorize for Site** dropdown and click **Accept** to complete the integration. -6. After approving the connection, click **Test Integration**. If everything is correct, the **Finish Step** appears. You are advised to click **Next** to complete the Integration by creating a profile. - -#### **Connect Jira Self-Managed to Xray using OAuth2** - -1. In the JFrog Platform: - 1. Navigate to **Administration > Xray Settings > Integration**. Click **Add Jira Integration**. A window opens up where you can configure the integration. - 2. Under **Installation Type** select **Server**. Under **Authentication Type** select **OAuth2**. Add an Integration Name and click on **Next**. - 3. Click on the copy icon to copy the callback URL and proceed to the next step. -2. In the Jira platform: - 1. Navigate to the **Administration** page. Under the options of Integrations select the **Application links** tab. - 2. Click the **Create Link** button to create a new Application link. This will be used to connect to Xray. To learn more about Application links, see [here](https://confluence.atlassian.com/adminjiraserver/link-to-other-applications-938846918.html). - - A window appears for creating the Application link. - 3. Under **Application type** select **External application**. Under **Direction** select Incoming. Click **Continue**. - - You will be redirected to the page for configuring the incoming link. - 4. Add a name for the link. Paste the callback URL from Xray in the Redirect URL input. From the **Permission** dropdown, select **Write**. Click **Save**. - - You will now be taken to the **Credentials** page where the **Client ID** and **Client Secret** will be shown. They will be needed in the next step. -3. In the JFrog Platform: - 1. Copy the **Client ID** and **Client Secret** from the previous step and paste them under the Client ID and Secret inputs in Xray. Add the base URL of the Jira instance under the **Jira URL**. Click **Next**. - 2. A window opens asking for approval of the connection. Click **Allow**. - 3. After approving the connection, click **Test Integration**. If everything is correct, the **Finish Step** appears. You are advised to click **Next** to complete the Integration by creating a profile. - -#### **Connect Jira to Xray Using Basic Authentication** - -1. In the installation type select **Basic Integration** and add the integration name. -2. In your Jira account create an API Token. Use this link: [https://id.atlassian.com/manage-profile/security/api-tokens](https://id.atlassian.com/manage-profile/security/api-tokens) - - For more information, see [https://developer.atlassian.com/server/jira/platform/basic-authentication/](https://developer.atlassian.com/server/jira/platform/basic-authentication/) -3. From the Xray Jira wizard, provide the following: - * The created API token - * Jira URL - * Your User Name"(email that Jira integration is registered) -4. Click **Next**. - - You are all set. Continue to the next step, [Profile Creation](broken-reference). - -### Create Jira Configuration Profile - -After completing the connection between Jira and Xray, you need to create a Jira Configuration profile. As there are different Jira projects for different teams, the configuration profile enables you to define specific criteria for the issued Jira ticket per Jira project, such as labels and custom mappings defined in the Jira project. - -> #### Note -> -> Xray supports the below field types of Jira if you have any other type as a required field, these issue types will not appear in the “Issue Type” list of the profile configuration page: -> -> * Short Text -> * Paragraph (Xray does not support rich text) -> * Drop Down -> * Check Box / Check Boxes -> * Labels -> * Number -> * Radio Buttons -> * Select List (multiple choices) -> * Select List (single choice) - - - -**Macros** - -Xray provides a list of Macros, which you can map to your Custom Fields or Labels of the Jira Project. We would resolve these Macros for a violation and assign appropriate values to the custom fields as part of the ticket creation.Here are the available macros: - -* Impacted Artifact -* Impacted Component -* Package Type -* Vulnerability ID -* Violation Type -* Severity -* Severity Source -* JFrog Research Severity -* CVE -* CVSS V2 Vector -* CVSS V2 Score -* CVSS V3 Vector -* CVSS V3 Score -* CVSS V2 Access Complexity -* CVSS V2 Attack Vector -* CVSS V3 Attack Complexity -* CVSS V3 Attack Vector -* Fix Version -* Watch Name -* Policy Name -* Triggered Rule -* Component License ID -* Fix Version Available? -* CVE Applicable -* Exposure Fix Cost - -Example: - -Consider you have a Jira Project called “Xray” and would like to configure the “Security” issue type as a profile and create tickets under it for any violations. Here are the steps you would follow: - -1. The issue type “Security” is configured as below. -2. Note the custom field “Severity” added to the context fields. “Severity” has the below configuration. -3. Now, while creating the profile, you select “Xray” as the project type and “Security” as the issue type. Xray automatically lists all the required mandatory fields; in this case, you can see “Severity” listed here. -4. In “Severity”, you will see two types of options to select: “Dynamic Value” and “Static Value.” These are the options to select an Xray Macro or one of the options you have set in the Jira Custom Field Configurations. Xray displays the most suitable macros based on your custom field configuration. -5. Assign the Xray macro “Severity” to the Jira custom field; as soon you do this, you will see a popup prompting you to provide a default value. When you map a macro to a mandatory custom field, we need a default value, which we will use while creating the ticket. For example, when a CVE is reported, there may not be a Severity in this case. What would you want to see in the Jira ticket? -6. You may also want to add a “Label” when Xray creates a ticket. Label is an optional field during ticket generation, you must add that to the profile before editing it. Click “Add Optional Fields” and add Labels to the profile page. -7. You could select one of the Xray Macros or type in a static text or both. Note that white spaces are not allowed in Jira Labels, these will be replaced by \_ (underscores) in the Jira ticket. -8. To validate your configurations, try “Creating a test ticket.” -9. Save your profile. - -Enable the Jira ticket creation in the Policy rules. In **Policy > Policy Rules > Automatic Actions**, select the **Create Jira Ticket** checkbox to trigger the creation of Jira tickets when violations are found that match the rule you defined in the Policy. - -To create a Jira ticket based on validation found in Watch resources, you must add a default Jira Profile. This profile will be used as the default profile to generate all the tickets. - -For more advanced configuration, click the Advanced Settings: - -* **Ticket duplication** - - If you need tickets duplication for every artifact version, select the checkboxes. Most commonly left unchecked. -* **Create tickets by impact path** - - This section allows you to create multiple tickets for the same violation or map the violation to a different Jira profiles. The tickets will be created based on the violation impact paths; all the tickets that do not match the mapped impact path will be created in the default profile. See the provided Best Practices for an elaborate example. -* **Create tickets for ignored violations** - - If you want tickets generated for ignored violations, turn this feature on. By default, JFrog Xray does not generate tickets for ignored violations. - - - -When the tickets are created, you can see the Jira icons against the violation, and the details view in the UI. - -In Xray reports, the violations reports of Xray, also have the ticket ID wherever applicable. - - - -## Jira Ticket Manual Creation - -In addition to automatic creation of Jira ticket, Xray enables you to create a Jira ticket for the following issue types manually: - -* Violations (all types) - * Operational risk - * License violation - * Security - -> #### More Permissions for OAuth2 -> -> If you have set up Jira integration with Xray using OAuth2, manual creation of Jira tickets requires some extra permissions.Ensure that the permissions are updated before manually creating Jira tickets. For more information, seeConnecting Jira to Xray Using OAuth2. - - - -To manually create a Jira ticket: - -1. In the **Application** tab, navigate to a violation on one of the following pages: - * **Artifactory > Builds** - * **Artifactory > Artifacts** - * **Scans List > Repositories** - * **Scans List > Builds** - * **Scans List > Release Bundles** - * **Watch Violations** -2. Click the vulnerability ID, and in the window that appears on the right, click the action button (three dots) and click **Create a Jira**. -3. In the **Create a Jira Ticket** window, update the following fields: - - | Field | Description | - | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | - | **Profile Name** |

This dropdown lists all the Jira configuration profiles that were defined when creating the Jira integration.

Click to select the relevant profile.

| - | **Issue Type** | This is auto-filled according to the profile selection. | - | **Labels** | This is auto-filled with all the labels. The drop-down displays the labels on the profile integration page. While you can remove the label from the field, it will not delete it from the main profile integration. | - | **Component** | This is auto-filled. The drop-down lists all the components affected by the vulnerability and all components are selected by default. You have the option of selecting a subset of the listed components. | - | **Title** | The is auto-filled based on the type of violation. | - | **Description** |

This is auto-filled and cannot be edited.

Description is auto-filled based on the violation's current state and the selected components. If the components are changed, the description is updated accordingly.

| - | **User comment** | Add relevant comments for the ticket. | -4. Click **Create**. - -> #### Note -> -> If a ticket has already been created for the issue, you have the option of updating it. - -Whenever a Jira ticket is manually created for a violation, it is indicated with an icon . Hover over the icon to see the list of Jira tickets that have already been created for the violation. If there are multiple tickets, the last created ticket will be the leading ticket. - -The Jira indicator along with the Jira Id is also shown on the Details screen. Clicking on a Jira Id redirects you to the Jira page for that ticket. - -To manually update a Jira ticket: - -1. In the **Application** tab, navigate to a violation on one of the following pages: - * **Artifactory > Builds** - * **Artifactory > Artifacts** - * **Scans List > Repositories** - * **Scans List > Builds** - * **Scans List > Release Bundles** - * **Watch Violations** -2. Click the vulnerability ID that already has a Jira indication, and in the window that appears on the right, click the action button (three dots) and click **Update a Jira**. -3. In the **Update a Jira Ticket** window: - 1. If there are multiple tickets, click the **Jira Ticket Number** drop-down to select the ticket to be updated. - 2. Scroll down to the **Add Comments** field and add relevant comments for the ticket. -4. Click **Update**. - - The **Title** and **Description** are automatically updated based on the current state of the violation. - -> #### Note -> -> If you try to update a ticket that has already been deleted, a message is displayed to that effect and you will have the option of creating a new ticket. - -## Best Practices - - - -Creating effective and manageable tickets in Jira or any issue-tracking system is crucial for maintaining an efficient workflow, clear communication, and project management. - -A few strategies curated by Atlassian around organizing Projects are as follows, - -* Releasable product: Organizing your projects by releasable products or groups of work that share a common release cycle. -* Team-based projects are another common organizational model. This allows your work to mirror your social organization and is convenient in less cross-functional setups, as it allows for more straightforward project permission management. -* Business Unit: Closely related to organizing around teams, you might also consider organizing around larger business units - marketing, product, IX, IT, etc. Types of work will likely fall into similar patterns, making setting up workflows - and issue types particularly - more convenient. -* Components: Be aware that using components, you can still sub-categorize issues within a given project. - -We have seen our clients mix these strategies to have a solution that reflects their operational model. - -**Releasable Product** - -Your Jira will have a Project representing a “Product”. This project will be used to track all activities for the product. - -When creating a releasable product, various teams within the same group will work together to produce the final artifact. For instance, the engineering team will develop the core product while the dev ops team will create artifacts for log shipping, deployment, and other related tasks. Additionally, the database team will provide utilities for initializing and migrating the database. - -After scanning the final artifact, you may come across violations that need to be addressed by various teams depending on the impact path. In some cases, different teams may work together to resolve a CVE. For tracking purposes in Jira, you can assign relevant "Components" fields in each ticket. - -Xray's Jira Integration supports this organizational structure. Set up three profiles for the same Jira Project with different components. - -Afterwards, you will configure the relevant watch as follows. Here, we add two entries in the advanced settings to create a separate ticket whenever a violation affects anything under '\*\*/DevOps/\*\*' and '\*\*/database/\*\*' - -Xray applies settings for each of the violations generated by the Watch. We examine the impact paths affected by the violation. If any of the paths match the specified patterns, a separate ticket is created under the corresponding mapped profile. - -If there are no advanced settings or the violation does not have an impact path that matches the pattern, a ticket is created with all violation details under the default profile mapped to the Watch. In the given example, the default profile is "Xray-Security-Core." - -**Team-Based / Business Unit** - -To organize your work effectively in Jira, you can create separate projects for each team or business unit (BU) in your organization. This way, different teams can collaborate on the same product, but each team will have its own Jira project. - -To ensure you receive updates for each specific project, you must create a separate profile for each Jira project. You can then use these profiles in your watches with path-based patterns. - -**Profile Naming Conventions** - -Have you noticed the naming conventions we use for profiles? They follow the format of "\{{Jira Project\}} - \{{Issue Type\}} - \{{What’s this for\}}". This format helps Xray users understand the intention of each profile, even if they do not have permission to review the Jira integration in Xray. diff --git a/products/xray/integrations/webhooks.md b/products/xray/integrations/webhooks.md deleted file mode 100644 index 2ebc750..0000000 --- a/products/xray/integrations/webhooks.md +++ /dev/null @@ -1,20 +0,0 @@ -# Webhooks - -One of the options when configuring Watches is to have them invoke webhooks, which are proprietary URLs you can define to perform custom actions as a result of a violation being issued. Webhooks are configurable in the **Administration** module under **Xray | Webhooks**. - -## Adding a Webhook - -To add a webhook, click **New Webhook**. - -![DB Sync](../../../../.gitbook/assets/webhook-image.png) - -### Webhook Fields - -| Field | Description | -| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- | -| **Webhook Name** | An identifier for the webhook. This is the name that will be used by any Watches that want to invoke the webhook in case of a violation. | -| **URL** | The URL that this webhook invokes. For details of the payload provided by Xray to the webhook, please refer to [Webhook Payload](webhooks.md). | -| **Description** | A free text description. | -| **Use Proxy** | Set the webhook to go through the predefined proxy. For more information, see [Managing Proxies](webhooks.md). | -| **Basic Auth** | User Name/Password: A username and password as required by the webhook. | -| **Custom Headers** | Any custom headers that may need to be added to invoke the webhook. |