Skip to content

Commit bfd9097

Browse files
xieshenzhxieshenzh
authored
chore: correct the docs (#129)
* chore: update the docs * chore: update docs for settings * chore: update change notes * fix: typo in the settings form
1 parent dc3e21d commit bfd9097

File tree

8 files changed

+457
-141
lines changed

8 files changed

+457
-141
lines changed

‎README.md‎

Lines changed: 200 additions & 54 deletions
Original file line numberDiff line numberDiff line change
@@ -1,74 +1,220 @@
1-
# Dependency Analytics
1+
# Red Hat Dependency Analytics
22

33
[plugin-repo]: https://plugins.jetbrains.com/plugin/12541-dependency-analytics
4+
45
[plugin-version-svg]: https://img.shields.io/jetbrains/plugin/v/12541-dependency-analytics.svg
6+
57
[plugin-downloads-svg]: https://img.shields.io/jetbrains/plugin/d/12541-dependency-analytics.svg
68

79
![Java CI with Gradle](https://github.com/redhat-developer/intellij-dependency-analytics/workflows/Java%20CI%20with%20Gradle/badge.svg)
810
[![JetBrains plugins][plugin-version-svg]][plugin-repo]
911
[![JetBrains plugins][plugin-downloads-svg]][plugin-repo]
1012

11-
Dependency Analytics is powered by [Snyk Intel Vulnerability DB](https://snyk.io/product/vulnerability-database/). It is the most advanced and accurate open source vulnerability database in the industry, that adds value with the latest, fastest and most number of vulnerabilities derived from numerous sources.
12-
13-
'Dependency Analytics Report' with Insights about your application dependencies:
14-
15-
- Flags a security vulnerability(CVE) and suggests a remedial version
16-
- Shows Github popularity metrics along with latest version
17-
- Suggests a project level license, check for conflicts between dependency licences
18-
- AI based guidance for additional, alternative dependencies
19-
20-
> **Disclaimer**: Dependency Analytics does not analyse **dev/test** dependencies.
21-
22-
## Supported Languages
23-
24-
'Dependency Analytics' plugin supports Java (Maven), Npm (Node), Python and Golang projects.
25-
Extending support for other languages is currently under progress.
26-
27-
> **NOTE** Dependency Analytics is an online service hosted and maintained by Red Hat. This open source software will access only your manifests file(s) to learn about application dependencies before giving you the report.
28-
29-
## Prerequisites
30-
This plug-in assumes that you have installed all packages given in target manifest file which will be used to create transitive dependency for showing Stack Analysis, you also need to have following binaries on your IDE PATH:
31-
32-
- mvn (for analyzing Java applications)
33-
- npm (for analyzing Node applications)
34-
- python (for analyzing Python applications)
35-
- go (for analyzing Golang applications)
36-
37-
**Note**: In this plug-in mvn/npm/go/python commands are executed using 'ProcessBuilder', which requires that binaries for thse are found in your IDE Environment PATH.
38-
39-
## Quick Start
40-
41-
- Install the plugin.
42-
- Opening or editing a manifest file (pom.xml / package.json / requirements.txt / go.mod) scans your application for security vulnerabilities.
43-
- Click on icon from 'Navigation bar' or right click on a manifest file (pom.xml/package.json / requirements.txt / go.mod) in the 'File explorer' or 'File editor' to display 'Dependency Analytics Report' for your application.
13+
Red Hat Dependency Analytics (RHDA) plugin gives you awareness to security concerns within your software supply chain
14+
while you build your application.
15+
The Dependency Analytics plugin uses the Snyk REST API to
16+
query [Snyk's Vulnerability Database](https://snyk.io/product/vulnerability-database/) for the most up-to-date
17+
vulnerability information available.
18+
Snyk uses industry-leading security intelligence by pulling from many data sources to give you exact vulnerability
19+
information.
20+
21+
**NOTE:**
22+
<br >The Red Hat Dependency Analytics plugin is an online service hosted and maintained by Red Hat.
23+
Dependency Analytics only accesses your manifest files to analyze your application dependencies before displaying the
24+
vulnerability report.
25+
26+
**IMPORTANT:**
27+
<br >Currently, Dependency Analytics only supports projects that use Maven (`mvn`), and Node ecosystems (`npm`).
28+
In future releases, Red Hat plans to support other programming languages.
29+
30+
##### Table of Contents
31+
32+
- [Quick start](#quick-start)
33+
- [Configuration](#configuration)
34+
- [Features](#features)
35+
- [Know more about the Red Hat Dependency Analytics platform](#know-more-about-the-red-hat-dependency-analytics-platform)
36+
- [Data and telemetry](#data-and-telemetry)
37+
- [Support, feedback \& questions](#support-feedback--questions)
38+
- [License](#license)
39+
40+
## Quick start
41+
42+
**Prerequisites**
43+
44+
- For Maven projects, analyzing a `pom.xml` file, you must have the `mvn` binary in your IDE's `PATH` environment.
45+
- For Node projects, analyzing a `package.json` file, you must have the `npm` binary in your IDE's `PATH` environment.
46+
47+
**Procedure**
48+
49+
1. Install [IntelliJ IDEA](https://www.jetbrains.com/idea/download/) on your workstation.
50+
2. After the installation finishes, open the IntelliJ IDEA application.
51+
3. From the menu, click **Settings** , and click **Plugins**.
52+
4. Search the **Marketplace** for _Red Hat Dependency Analytics_.
53+
5. Click the **INSTALL** button to install the plugin.
54+
6. To start scanning your application for security vulnerabilities, and view the vulnerability report, you can do one of
55+
the following:
56+
- Open a manifest file, hover over a dependency marked by the inline Component Analysis, indicated by the wavy-red
57+
line under a dependency, and click **Detailed Vulnerability Report**.
58+
- Right click on a manifest file in the **Project** window, and click **Dependency Analytics Report**.
59+
7. (OPTIONAL) You can link your Snyk account to Dependency Analytics by doing the following:
60+
1. Log into
61+
your [Snyk account](https://app.snyk.io/login?utm_campaign=Code-Ready-Analytics-2020&utm_source=code_ready&code_ready=FF1B53D9-57BE-4613-96D7-1D06066C38C9).
62+
2. On the account landing page, you can find your Snyk Token, copy the token.
63+
3. Set the Snyk token as the value of your IDE's `EXHORT_SNYK_TOKEN` environment.
64+
4. After adding your Snyk token, the vulnerability report gives you detailed information about security
65+
vulnerabilities unique to Snyk, and vulnerabilities that have publicly known exploits.
66+
67+
## Configuration
68+
69+
The Red Hat Dependency Analytics plugin has some configurable parameters that allows you to customize its behavior
70+
according to your preferences.
71+
72+
**Procedure**
73+
74+
1. Open the IntelliJ IDEA application.
75+
2. From the menu, click **Settings** , and click **Tools**.
76+
3. Click **Red Hat Dependency Analytics**.
77+
78+
![Red Hat Dependency Analytics plugin settings](src/main/resources/images/settings.png)
79+
80+
### Configurable parameters
81+
82+
**Maven** :
83+
<br >Path of the `mvn` executable allows Exhort to locate and execute the `mvn` commands to resolve dependencies for
84+
Maven projects.
85+
Path of the `JAVA_HOME` directory is required by the `mvn` executable.
86+
If the paths are not provided, your IDE's `PATH` and `JAVA_HONE` environments will be used to locate the executables.
87+
88+
**Npm** :
89+
<br >Path of the `npm` executable allows Exhort to locate and execute `npm` commands to resolve dependencies for Node
90+
projects.
91+
Path of the directory containing the `node` executable is required by the `npm` executable.
92+
If the paths are not provided, your IDE's `PATH` environment will be used to locate the executables.
93+
94+
**Exhort Snyk Token** :
95+
<br >The Snyk token allows Exhort to authenticate with the Snyk Vulnerability Database.
96+
If a Snyk token is not provided, Snyk vulnerability information is not displayed.
97+
98+
If you need a new Snyk token, you can generate a new
99+
token [here](https://app.snyk.io/login?utm_campaign=Code-Ready-Analytics-2020&utm_source=code_ready&code_ready=FF1B53D9-57BE-4613-96D7-1D06066C38C9).
44100

45101
## Features
46102

47-
1. Opening or editing a manifest file (`pom.xml` / `package.json` / `requirements.txt` / `go.mod`) scans your application for security vulnerabilities, flag them along with 'quick fixes'.
48-
49-
![ screencast ](src/main/resources/images/demo.gif)
50-
103+
- **Component analysis**
104+
<br >Upon opening a manifest file, such as a `pom.xml` or `package.json` file, a scan starts the analysis process.
105+
The scan provides immediate inline feedback on detected security vulnerabilities for your application's dependencies.
106+
Such dependencies are appropriately underlined in red, and hovering over it gives you a short summary of the security
107+
concern.
108+
The summary has the full package name, version number, the amount of known security vulnerabilities, and the highest
109+
severity status of said vulnerabilities.
110+
111+
![ Animated screenshot showing the inline reporting feature of Dependency Analytics ](src/main/resources/images/component-analysis.gif)
112+
113+
- **Excluding dependencies with `exhortignore`**
114+
<br >You can exclude a package from analysis by marking the package for exclusion.
115+
If you wish to ignore vulnerabilities for a dependency in a `pom.xml` file, you must add `exhortignore` as a comment
116+
against the dependency, group id, artifact id, or version scopes of that particular dependency in the manifest file.
117+
For example:
118+
119+
```xml
120+
<dependency> <!--exhortignore-->
121+
<groupId>...</groupId>
122+
<artifactId>...</artifactId>
123+
<version>...</version>
124+
</dependency>
125+
```
126+
127+
If you wish to ignore vulnerabilities for a dependency in a `package.json` file, you must add `exhortignore` as a
128+
attribute-value pair.
129+
If `exhortignore` is followed by a list of comma-separated Snyk vulnerability IDs, only the listed vulnerabilities
130+
will be ignored during analysis.
131+
For example:
132+
133+
```json
134+
{
135+
"name": "sample",
136+
"version": "1.0.0",
137+
"description": "",
138+
"main": "index.js",
139+
"keywords": [],
140+
"author": "",
141+
"license": "ISC",
142+
"dependencies": {
143+
"dotenv": "^8.2.0",
144+
"express": "^4.17.1",
145+
"jsonwebtoken": "^8.5.1",
146+
"mongoose": "^5.9.18"
147+
},
148+
"exhortignore": [
149+
"jsonwebtoken"
150+
]
151+
}
152+
```
153+
154+
- **Excluding developmental or test dependencies**
155+
<br >Red Hat Dependency Analytics does not analyze dependencies marked as `dev` or `test`, these dependencies are
156+
ignored.
157+
For example, setting `test` in the `scope` tag within a `pom.xml` file:
158+
159+
```xml
160+
<dependency>
161+
<groupId>...</groupId>
162+
<artifactId>...</artifactId>
163+
<version>...</version>
164+
<scope>test</scope>
165+
</dependency>
166+
```
167+
168+
For example, setting `devDependencies` attributte in the `package.json` file:
169+
170+
```json
171+
{
172+
"name": "sample",
173+
"version": "1.0.0",
174+
"description": "",
175+
"main": "index.js",
176+
"keywords": [],
177+
"author": "",
178+
"license": "ISC",
179+
"dependencies": {
180+
"dotenv": "^8.2.0",
181+
"express": "^4.17.1",
182+
"jsonwebtoken": "^8.5.1",
183+
"mongoose": "^5.9.18"
184+
},
185+
"devDependencies": {
186+
"axios": "^0.19.0"
187+
}
188+
}
189+
```
190+
191+
- **Red Hat Dependency Analytics report**
192+
<br >The Red Hat Dependency Analytics report is a temporary HTML file that exist if the **Red Hat Dependency Analytics
193+
Report** tab remains open.
194+
Closing the tab removes the temporary HTML file.
195+
196+
## Know more about the Red Hat Dependency Analytics platform
197+
198+
The goal of this project is to significantly enhance a developer's experience by providing helpful vulnerability
199+
insights for their applications.
51200

52-
2. Right click on a manifest file(`pom.xml` / `package.json` / `requirements.txt` / `go.mod`) and choose 'Dependency Analytics Report ...' OR click on ![icon](src/main/resources/images/report-icon.png) icon in navigation bar to display 'Dependency Analytics' report as shown below. This report covers deeper insights into your application dependencies:
53-
54-
- Flags a security vulnerability(CVE) and suggests a remedial version
55-
- Shows Github popularity metrics along with latest version
56-
- Suggests a project level license, check for conflicts between dependency licences
57-
- AI based guidance for additional,alternative dependencies
58-
59-
![ screencast ](src/main/resources/images/stack-analysis.gif)
201+
- [GitHub Organization](https://github.com/redhat-developer)
60202

61-
# Know more about Dependency Analytics Platform
203+
## Data and telemetry
62204

63-
The mission of this project is to significantly enhance developer experience:
64-
providing Insights(security) for applications and helping developers, Enterprises.
205+
The Red Hat Dependency Analytics plugin for IntellJ IDEA collects anonymous [usage data](USAGE_DATA.md) and sends it to
206+
Red Hat servers to help improve our products and services.
207+
Read our [privacy statement](https://developers.redhat.com/article/tool-data-collection) to learn more.
208+
This plugin respects the settings of the `Telemetry by Red Hat` plugin, which you can learn more
209+
about [here](https://plugins.jetbrains.com/plugin/16209-telemetry-by-red-hat).
65210

66-
- [GitHub Organization](https://github.com/redhat-developer)
211+
## Support, feedback & questions
67212

68-
# Feedback & Questions
213+
There are two ways you can contact us:
69214

70-
- File a bug in [GitHub Issues](https://github.com/redhat-developer/intellij-dependency-analytics/issues)
215+
- You can reach out to us at `[email protected]` with any questions, feedback, and general support.
216+
- You can also file a [GitHub Issue](https://github.com/redhat-developer/intellij-dependency-analytics/issues).
71217

72-
# License
218+
## License
73219

74-
EPL 2.0, See [LICENSE](LICENSE) for more information.
220+
EPL 2.0, See [LICENSE](LICENSE) for more information.

‎USAGE_DATA.md‎

Lines changed: 4 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,8 @@
1-
## [Dependency Analytics](https://github.com/redhat-developer/intellij-dependency-analytics)
1+
## [Red Hat Dependency Analytics](https://github.com/redhat-developer/intellij-dependency-analytics)
22

33
### Usage Data
44

55
* when plugin is started
6-
* when server is downloaded
7-
* when a component analysis is done
8-
* when plugin is shut down
9-
6+
* when plugin analyse dependency file for vulnerability(s) and file name
7+
* when plugin analyse dependency file fails, error message and file name
8+
* when plugin is shutdown

‎src/main/java/org/jboss/tools/intellij/settings/ApiSettingsComponent.java‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -32,7 +32,7 @@ public class ApiSettingsComponent {
3232
private final static String nodePathLabel = "<html>Node > Directory: <b>Path</b>"
3333
+ "<br>Specifies absolute path of the <i>directory</i> containing <b>node</b> executable.</html>";
3434
private final static String snykTokenLabel = "<html>Red Hat Dependency Analytics: <b>Exhort Snyk Token</b>"
35-
+ "<br>Red Hat Dependency Analytics sever authentication token for Snky.</html>";
35+
+ "<br>Red Hat Dependency Analytics sever authentication token for Snyk.</html>";
3636

3737
private final JPanel mainPanel;
3838

0 commit comments

Comments
 (0)