diff --git a/README.md b/README.md index a39499a4..5de653ce 100644 --- a/README.md +++ b/README.md @@ -12,31 +12,7 @@ -# Table of Contents - -- [About this Plugin](#about-this-plugin) -- [Supported Packages](#supported-packages) -- [Getting Started](#getting-started) - - [Connecting to Your JFrog Environment](#connecting-to-your-jfrog-environment) - - [Apply Xray Policies](#apply-xray-policies) -- [Using the Plugin](#using-the-plugin) - - [The Local View](#the-local-view) - - [Scanning a Project](#scanning-a-project) - - [Viewing Vulnerability Details](#viewing-vulnerability-details) - - [CVEs Contextual Analysis](#cves-contextual-analysis) - - [Secrets Detection](#secrets-detection) - - [Infrastructure as Code (IaC) Scan](#infrastructure-as-code-iac-scan) - - [Severity Icons](#severity-icons) - - [The CI View](#the-ci-view) - - [How Does It Work?](#how-does-it-work) - - [Setting Up CI Integration](#setting-up-ci-integration) -- [Android Studio Support for JCEF](#android-studio-support-for-jcef) -- [Troubleshooting](#troubleshooting) -- [Reporting Issues](#reporting-issues) -- [Contributions](#contributions) -- [Release Notes](#release-notes) - -# About this Plugin +# πŸ€– About this Plugin The plugin allows developers to find and fix security vulnerabilities in their projects and to see valuable information about the status of their code by continuously scanning it locally with [JFrog Security](https://jfrog.com/xray/). @@ -98,258 +74,18 @@ In addition to IntelliJ IDEA, the plugin also supports the following IDEs: - Android Studio - GoLand -# Supported Packages - -| Features | Go | Maven | Gradle / Kotlin | npm | Yarn v1 | Python | Terraform | -|---------------------------------------------------|:--:|:-----:|:---------------:|:---:|:-------:|:------:|:---------:| -| Software Composition Analysis (SCA) | βœ… | βœ… | βœ… | βœ… | βœ… | βœ… | ❌ | -| CVE Research and Enrichment | βœ… | βœ… | βœ… | βœ… | βœ… | βœ… | ❌ | -| Upgrade vulnerable dependencies to fixed versions | βœ… | βœ… | βœ… | βœ… | βœ… | ❌ | ❌ | -| CVEs Contextual Analysis | ❌ | βœ… | βœ… | βœ… | βœ… | βœ… | ❌ | -| Secrets Detection | βœ… | βœ… | βœ… | βœ… | βœ… | βœ… | βœ… | -| Infrastructure as Code (IaC) Scan | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | βœ… | - -# Getting Started - -1. Install the JFrog IntelliJ IDEA Plugin via the Plugins tab in the IDE settings, or in [JetBrains Marketplace](https://plugins.jetbrains.com/plugin/9834-jfrog). -2. [Connect the plugin to your JFrog environment](#connecting-to-your-jfrog-environment). -3. [Start](#using-the-plugin) using the plugin. - -## Connecting to Your JFrog Environment - -
- Optionally set up a free JFrog Environment in the Cloud -Need a free JFrog environment in the Cloud, so that JFrog IntelliJ IDEA Plugin can connect to it? Just run one of the following commands in your terminal. The commands will do the following: - -1. Install JFrog CLI on your machine. -2. Create a FREE JFrog environment in the Cloud for you. -3. Configure IntelliJ IDEA to connect to your new environment. - -**MacOS and Linux using cURL** - -```bash -curl -fL https://getcli.jfrog.io?setup | sh -``` - -**Windows using PowerShell** - -```powershell -powershell "Start-Process -Wait -Verb RunAs powershell '-NoProfile iwr https://releases.jfrog.io/artifactory/jfrog-cli/v2-jf/[RELEASE]/jfrog-cli-windows-amd64/jf.exe -OutFile $env:SYSTEMROOT\system32\jf.exe'" ; jf setup -``` - -
- -
- Connect the JFrog Plugin to an existing JFrog Environment - -You can connect the plugin to your JFrog environment using one of the following methods: - -
- Using the IDE Settings - Once the plugin is successfully installed, connect the plugin to your instance of the JFrog Platform: - - 1. If your JFrog Platform instance is behind an HTTP proxy, configure the proxy settings as described [here](https://www.jetbrains.com/help/idea/settings-http-proxy.html). - Manual proxy configuration is supported since version 1.3.0 of the JFrog IntelliJ IDEA Plugin. Auto-detect proxy settings is supported since version 1.7.0. - 2. Under **Settings (Preferences)** | **Other Settings**, click **JFrog Global Configuration**. - 3. Set your JFrog Platform URL and login credentials. - 4. Test your connection to Xray using the Test Connection button. - - ![](readme-resources/connect.png) -
- -
- Using Environment Variables -The plugin also supports connecting to your JFrog environment using environment variables: - -1. Under **Settings (Preferences)** | **Other Settings**, click **JFrog Global Configuration**. -2. Mark **Load connection details from environment variables**. - -You may provide basic auth credentials or access token as follows: - -> **_NOTE:_** For security reasons, it is recommended to unset the environment variables after launching the IDE. - -- `JFROG_IDE_PLATFORM_URL` - JFrog Platform URL -- `JFROG_IDE_USERNAME` - JFrog Platform username -- `JFROG_IDE_PASSWORD` - JFrog Platform password -- `JFROG_IDE_ACCESS_TOKEN` - JFrog Platform access token - -
-
- -> **NOTES:** -> - If your JFrog Platform instance uses a domain with a self-signed certificate, add the certificate to IDEA as described [here](https://www.jetbrains.com/help/idea/settings-tools-server-certificates.html). -> - From JFrog Xray version **1.9** to **2.x**, IntelliJ IDEA users connecting to Xray from IntelliJ are required to be granted the β€˜View Components’ action in Xray. -> - From JFrog Xray version **3.x**, as part of the JFrog Platform, IntelliJ IDEA users connecting to Xray from IntelliJ require β€˜Read’ permission. For more information, see [here](https://jfrog.com/help/r/jfrog-platform-administration-documentation/permissions). - -## Apply Xray Policies - -You can configure the JFrog IntelliJ IDEA Plugin to use the security policies you create in Xray. -Policies enable you to create a set of rules, in which each rule defines security criteria, with a corresponding set of automatic actions according to your needs. -Policies are enforced when applying them to Watches. - -If you'd like to use a JFrog Project that is associated with the policy, follow these steps: - -1. Create a [JFrog Project](https://jfrog.com/help/r/jfrog-platform-administration-documentation/introduction-to-projects), or obtain the relevant JFrog Project key. -2. Create a [Policy](https://jfrog.com/help/r/jfrog-security-documentation/creating-xray-policies-and-rules) on JFrog Xray. -3. Create a [Watch](https://jfrog.com/help/r/jfrog-security-documentation/configuring-xray-watches) on JFrog Xray and assign your Policy and Project as resources to it. -4. Configure your Project key in the plugin settings: under **Settings (Preferences)** | **Other Settings**, click **JFrog Global Configuration** and go to the **Settings** tab. - -If however your policies are referenced through Xray Watches, follow these steps instead: - -1. Create one or more [Watches](https://jfrog.com/help/r/jfrog-security-documentation/configuring-xray-watches) on JFrog Xray. -2. Configure your Watches in the plugin settings: under **Settings (Preferences)** | **Other Settings**, click **JFrog Global Configuration** and go to the **Settings** tab. - -# Using the Plugin - -After the JFrog Plugin is installed, a new JFrog panel is added at the bottom of the screen. -Opening the JFrog panel displays two views: - -- The **Local** view displays information about the local code as it is being developed in the IDE. - You can continuously scan your project locally. - The information is displayed in the **Local** view. -- The **CI** view allows the tracking of the code as it is built, tested and scanned by the CI server. - It displays information about the status of the build and includes a link to the build log on the CI server. - -## The Local View -### General -The JFrog IntelliJ IDEA Plugin enables continuous scans of your project with the JFrog Platform. The security related information will be displayed under the Local view. -It allows developers to view vulnerability information about their dependencies and source code in their IDE. -With this information, a developer can make an informed decision on whether to use a component or not before it gets entrenched into the organization’s product. - -Scan your project by clicking the Run Scan ![](readme-resources/run-scan-button.png) button. -After the scan is done, a list of vulnerable files will appear. - -### Software Composition Analysis (SCA) -Each descriptor file (like pom.xml in Maven, go.mod in Go, etc.) displayed in the JFrog Panel contains vulnerable dependencies, and each dependency contains the vulnerabilities themselves. - -By right-clicking on a dependency line, you can jump to the dependency's declaration in the descriptor file or have the depedency upgraded to a version with a fix. - -![](readme-resources/jump-to-descriptor.png) - -You can also create an [Ignore Rule](https://jfrog.com/help/r/jfrog-security-documentation/ignore-rules) in Xray. - -*Creating Ignore Rules is only available [when a JFrog Project or Watch is defined](#apply-xray-policies).* - -![](readme-resources/create-ignore-rule.png) - -Clicking a vulnerability in the list will open the vulnerability details view. -This view contains information about the vulnerability, the vulnerable component, fixed versions, impact paths and much more. - -![](readme-resources/vuln-details.png) -![](readme-resources/vuln-impact-graph.png) - -### CVEs Contextual Analysis - -*Requires Xray version 3.66.5 or above and Enterprise X / Enterprise+ subscription with Advanced DevSecOps.* - -Xray automatically validates some high and very high impact vulnerabilities, such as vulnerabilities that have prerequisites for exploitations, and provides contextual analysis information for these vulnerabilities, to assist you in figuring out which vulnerabilities need to be fixed. - -CVEs Contextual Analysis data includes: - -- **Contextual Analysis status**: Contextual Analysis results indicating if a CVE was found applicable in your application or not applicable. -- **Contextual Analysis breakdown**: An explanation provided by our research team as to why the CVE was found applicable or not applicable. -- **Remediation**: Contextual mitigation steps and options provided by our research team that assist you with remediating the issues. - -![](readme-resources/not-applicable.png) -![](readme-resources/applicable.png) - -### Secrets Detection - -*Requires Xray version 3.66.5 or above and Enterprise X / Enterprise+ subscription with Advanced DevSecOps.* - -Detect any secrets left exposed inside the code. to prevent any accidental leak of internal tokens or credentials. -> **NOTE:** To ignore detected secrets, you can add a comment which includes the phrase **jfrog-ignore** above the line with the secret. - -![](readme-resources/secrets.png) - -### Infrastructure as Code (IaC) Scan - -*Requires Xray version 3.66.5 or above and Enterprise X / Enterprise+ subscription with Advanced DevSecOps.* - -Scan Infrastructure as Code (Terraform) files for early detection of cloud and infrastructure misconfigurations. - -![](readme-resources/iac.png) -### Severity Icons - -The icon demonstrates the top severity issue of a selected component and its transitive dependencies. The following table describes the severities from highest to lowest: - -| Icon | Severity | -|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------:|:--------------------------------------:| -| | Critical | -| | High | -| | Medium | -| | Low | -| | Unknown | -| | [Not Applicable](#contextual-analysis) | - -## The CI View - -The JFrog IntelliJ IDEA Plugin allows you to view information about your builds directly from your CI system. -This allows developers to keep track of the status of their code, while it is being built, tested and scanned as part of the CI pipeline, regardless of the CI provider used. - -This information can be viewed inside IntelliJ IDEA, from the **JFrog** Panel, under the **CI** tab. - -The following details can be made available in the CI view: - -- Status of the build run (passed or failed) -- Build run start time -- Git branch and latest commit message -- Link to the CI run log -- Security information about the build artifacts and dependencies - -![](readme-resources/ci-view.png) - -### How Does It Work? - -The CI information displayed in IDEA is pulled by the JFrog IDEA Plugin directly from JFrog Artifactory. -This information is stored in Artifactory as part of the build-info, which is published to Artifactory by the CI server. -Read more about build-info in the [Build Integration](https://jfrog.com/help/r/jfrog-integrations-documentation/build-integration) documentation page. -If the CI pipeline is also configured to scan the build-info by JFrog Xray, the JFrog IDEA Plugin will pull the results of the scan from JFrog Xray and display them in the CI view as well. - -### Setting Up CI Integration - -Set up your CI pipeline to expose information, so that it is visible in IDEA as described [here](https://jfrog.com/help/r/jfrog-integrations-documentation/setting-up-ci-integration). - -Next, follow these steps: - -1. Under **Settings (Preferences)** | **Other Settings**, click **JFrog Global Configuration**. configure the JFrog Platform URL and the user you created. -2. Under **Settings (Preferences)** | **Other Settings**, click **JFrog CI Integration**. Set your CI build name in the **Build name pattern** field. This is the name of the build published to Artifactory by your CI pipeline. You have the option of setting * to view all the builds published to Artifactory. - ![](readme-resources/ci-settings.png) -3. Click **Apply** and open the **CI** tab under the **JFrog** panel at the bottom of the screen and click the **Refresh** button. - -# Android Studio Support for JCEF - -The JFrog IntelliJ IDEA Plugin uses JCEF (Java Chromium Embedded Framework) to create a webview component in the plugin's tool window. - -Most IntelliJ-based IDEs use a boot runtime that contains JCEF by default. - -Android Studio and some older versions of other IntelliJ-based IDEs use a boot runtime that doesn't contain JCEF by default, and therefore the plugin can't be loaded in them. - -To solve this issue, open the ["Choose Boot Runtime for the IDE"](https://www.jetbrains.com/help/idea/switching-boot-jdk.html) dialog where you can change the boot runtime to one that contains JCEF. - -# Troubleshooting - -The JFrog IntelliJ IDES Plugin uses the IntelliJ IDEA log files. By default, the log level used by the plugin is INFO. - -You have the option of increasing the log level to DEBUG. Here's how to do it: - -1. Go to **Help** | **Diagnostic Tools** | **Debug Log Settings...** -2. Inside the **Custom Debug Log Configuration** window add the following line: - -```java -#com.jfrog.ide.idea.log.Logger -``` +# 🏁 Getting Started -To see the Intellij IDEA log file, depends on the IDE version and OS as described [here](https://intellij-support.jetbrains.com/hc/en-us/articles/207241085-Locating-IDE-log-files), go to **Help** | **Show/reveal Log in Explorer/finder/Konqueror/Nautilus**. +Read the the [documentation](https://docs.jfrog-applications.jfrog.io/jfrog-applications/ide/jetbrains-ides) to get started. -# Reporting Issues +# πŸ”₯ Reporting Issues Please report issues by opening an issue on [GitHub](https://github.com/jfrog/jfrog-idea-plugin/issues). -# Contributions +# πŸ’» Contributions We welcome community contribution through pull requests. To help us improve this project, please read our [Contribution](./CONTRIBUTING.md#guidelines) guide. -# Release Notes +# πŸ₯ Release Notes The release notes are available on [Marketplace](https://plugins.jetbrains.com/plugin/9834-jfrog/versions). diff --git a/readme-resources/applicable.png b/readme-resources/applicable.png deleted file mode 100644 index 99e181a5..00000000 Binary files a/readme-resources/applicable.png and /dev/null differ diff --git a/readme-resources/ci-view.png b/readme-resources/ci-view.png deleted file mode 100644 index 57116504..00000000 Binary files a/readme-resources/ci-view.png and /dev/null differ diff --git a/readme-resources/connect.png b/readme-resources/connect.png deleted file mode 100644 index 25d74d88..00000000 Binary files a/readme-resources/connect.png and /dev/null differ diff --git a/readme-resources/create-ignore-rule.png b/readme-resources/create-ignore-rule.png deleted file mode 100644 index ef393594..00000000 Binary files a/readme-resources/create-ignore-rule.png and /dev/null differ diff --git a/readme-resources/iac.png b/readme-resources/iac.png deleted file mode 100644 index 03d8433c..00000000 Binary files a/readme-resources/iac.png and /dev/null differ diff --git a/readme-resources/jump-to-descriptor.png b/readme-resources/jump-to-descriptor.png deleted file mode 100644 index 353d6f61..00000000 Binary files a/readme-resources/jump-to-descriptor.png and /dev/null differ diff --git a/readme-resources/not-applicable.png b/readme-resources/not-applicable.png deleted file mode 100644 index 5499d1da..00000000 Binary files a/readme-resources/not-applicable.png and /dev/null differ diff --git a/readme-resources/run-scan-button.png b/readme-resources/run-scan-button.png deleted file mode 100644 index 713515a8..00000000 Binary files a/readme-resources/run-scan-button.png and /dev/null differ