Merge pull request #276 from SuperChen-CC/docs

update: docs
XmirrorSecurity · Jul 29, 2024 · 834daa2 · 834daa2
2 parents 91f4d3e + 32e7de3
commit 834daa2
Show file tree

Hide file tree

Showing 23 changed files with 985 additions and 2 deletions.
diff --git a/docs/Integrations/IDE_Plugins-zh_CN.md b/docs/Integrations/IDE_Plugins-zh_CN.md
@@ -0,0 +1,110 @@
+[返回目录](/docs/README-zh-CN.md) / [English](./IDE_Plugins.md)
+
+- [Visual Studio Code](#visual-studio-code)
+  - [安装插件](#安装插件)
+  - [使用插件](#使用插件)
+    - [插件功能](#插件功能)
+    - [插件执行流程](#插件执行流程)
+    - [运行扫描](#运行扫描)
+- [Jetbrains IDEs](#jetbrains-ides)
+  - [安装插件](#安装插件-1)
+  - [使用插件](#使用插件-1)
+    - [插件功能](#插件功能-1)
+    - [插件执行流程](#插件执行流程-1)
+    - [运行扫描](#运行扫描-1)
+
+
+# Visual Studio Code
+
+## 安装插件
+
+- **安装方法 一**：在 [VS Marketplace](https://marketplace.visualstudio.com/items?itemName=xmirror.opensca) 中安装（推荐）
+
+    在VS Code中左边栏打开扩展->扩展的搜索框中输入“OpenSCA Xcheck”，点击“Install”
+
+    <img src="https://opensca.xmirror.cn/docs/img/vscode_01.jpg" alt="xcheck_market" />
+
+- **安装方法二**：在[OpenSCA 官网](https://opensca.xmirror.cn/pages/plug-in)下载插件安装
+
+  - 从OpenSCA平台下载 “OpenSCA-Xcheck.vsix”；
+  - 打开VS Code，依次操作：左边栏打开扩展->扩展顶栏的更多操作->“从VSIX安装”->找到并安装“OpenSCA-Xcheck.vsix”；
+
+- **安装方法三**：[下载源码](https://github.com/XmirrorSecurity/)自行编译安装
+
+  - 环境要求：
+
+    - node v18及以上版本
+    - 系统支持MacOS、Windows、Linux
+
+  - 从[gitee](https://gitee.com/XmirrorSecurity/OpenSCA-VSCode-plugin)或[github](https://github.com/XmirrorSecurity/OpenSCA-VSCode-plugin/)下载源码
+
+  * 全局安装vsce
+
+    ```
+    npm install --global @vscode/vsce
+    ```
+
+  * 执行打包命令
+
+    ```
+    vsce package
+    ```
+
+## 使用插件
+
+### 插件功能
+
+- 开始检测：点击操作栏的“Run”，开始检测当前项目内的组件漏洞风险情况；
+- 停止检测：点击操作栏的“Stop”，停止检测当前项目内的组件漏洞风险情况；
+- 清除检测结果：点击操作栏的“Clean”，清除当前项目的检测结果；
+- 连接配置：点击操作栏的“Test”按钮，配置平台Url及Token信息，点击“测试连接”按钮可测试连接配置是否正确，连接成功后就可以开始检测啦；
+- 设置：点击操作栏的“Setting”，查看OpenSCA Xcheck相关设置信息。
+- 使用说明：点击操作栏的“Instructions”，查看OpenSCA Xcheck相关使用说明。
+- 查看更多：点击操作栏的“See more”，跳转到[opensca.xmirror.cn](https://opensca.xmirror.cn)查看OpenSCA Xcheck 更多相关信息。
+
+<img src="https://opensca.xmirror.cn/docs/img/vscode_02.jpg" alt="xcheck_function" />
+
+### 插件执行流程
+
+<img src="https://opensca.xmirror.cn/docs/assets/img/xcheck_process.7083b869.jpg" alt="xcheck流程图"  />
+
+### 运行扫描
+
+点击OpenSCA Xcheck可打开OpenSCA窗口。首先在配置界面中配置服务器参数（参考：插件功能-设置），然后在OpenSCA窗口中点击“Run”（参考：插件功能-开始检测）
+
+# Jetbrains IDEs
+
+## 安装插件
+
+- **安装方法一**：从 [Jetbrains 插件市场](https://plugins.jetbrains.com/plugin/18246-opensca-xcheck) 中安装（推荐）
+
+    以IntelliJ IDEA为例：在IDE中依次点击“File|Settings|Plugins|Marketplace”，在搜索框中输入“OpenSCA Xcheck”，点击“Install”
+    
+    ![xcheck_market](/resources/xcheck_marketplace.jpg)
+
+- **安装方法二**：在[OpenSCA平台](https://opensca.xmirror.cn/pages/plug-in )下载插件安装
+
+    以IntelliJ IDEA为例：将下载下来的插件安装包拖入适配的IDE中即可
+
+- **安装方法三**：[下载源码](https://github.com/XmirrorSecurity/OpenSCA-intellij-plugin )自行编译安装
+
+    使用IntelliJ IDEA打开下载到本地的源码，需要配置运行环境：`jDK11`，待Gradle导入依赖和插件，在Gradle中执行`intellij`插件的`buildPlugin`任务，构建的安装包存放于当前项目下*build/distributions*目录下，将此目录下的安装包拖入当前IDE中即可
+
+## 使用插件
+
+### 插件功能
+
+- 配置：点击File|Settings|Other Settings|OpenSCA Setting或点击OpenSCA窗口中的`Setting`按钮，在配置界面中配置连接服务器Url和Token
+- 测试连接：在OpenSCA配置界面中，配置服务器Url和Token之后点击`测试连接`按钮可验证Url和Token是否有效
+- 运行：点击OpenSCA窗口中的`Run`按钮，可对当前项目进行代码评估
+- 停止：如果正在对当前项目代码评估，那么`Stop`按钮是可用的，点击Stop按钮可结束当前评估任务
+- 清除：如果OpenSCA窗口中的Xcheck子窗口已有评估结果，点击`Clean`按钮可清除Xcheck子窗口中所有结果
+![xcheck_function](/resources/xcheck_function.jpg)
+
+### 插件执行流程
+
+![xcheck流程图](/resources/xcheck_process.jpg)
+
+### 运行扫描
+
+点击 `View` > `Tool Windows` > `OpenSCA` 可打开OpenSCA窗口。首先在OpenSCA配置界面中配置服务器参数（参考：插件功能-配置），然后在OpenSCA窗口中点击“运行”（参考：插件功能-运行）
diff --git a/docs/Integrations/IDE_Plugins.md b/docs/Integrations/IDE_Plugins.md
@@ -0,0 +1,108 @@
+[Go Back](/docs/README.md) | [简体中文](./IDE_Plugins-zh_CN.md)
+
+- [Visual Studio Code](#visual-studio-code)
+  - [Install Plugin](#install-plugin)
+  - [Using the Plugin](#using-the-plugin)
+    - [Plugin Features](#plugin-features)
+    - [Plugin Execution Process](#plugin-execution-process)
+    - [Running a Scan](#running-a-scan)
+- [JetBrains IDEs](#jetbrains-ides)
+  - [Installing the Plugin](#installing-the-plugin)
+  - [Using the Plugin](#using-the-plugin-1)
+    - [Plugin Features](#plugin-features-1)
+    - [Plugin Execution Process](#plugin-execution-process-1)
+    - [Running a Scan](#running-a-scan-1)
+
+# Visual Studio Code
+
+## Install Plugin
+
+- **Option 1**：Install from [VS Marketplace](https://marketplace.visualstudio.com/items?itemName=xmirror.opensca)
+
+    In VS Code, open Extensions in the left sidebar -> enter "OpenSCA Xcheck" in the extension search box, click "Install"
+
+    <img src="https://opensca.xmirror.cn/docs/img/vscode_01.jpg" alt="xcheck_market" />
+
+- **Option 2**：Download from [OpenSCA Official Web Site](https://opensca.xmirror.cn/pages/plug-in)
+
+  - Download "OpenSCA-Xcheck.vsix" from the OpenSCA official website;
+  - Open VS Code, open Extensions in the left sidebar -> more actions in the top bar of the extension -> "Install from VSIX" -> find and install "OpenSCA-Xcheck.vsix";
+
+- **Option 3**：Build from source code
+
+  - Requirements:
+    - node v18 and above
+
+  - Clone the repository from [github](https://github.com/XmirrorSecurity/OpenSCA-VSCode-plugin/) or [gitee](https://gitee.com/XmirrorSecurity/OpenSCA-VSCode-plugin)
+
+  * Install vsce
+
+    ```
+    npm install --global @vscode/vsce
+    ```
+
+  * Package
+
+    ```
+    vsce package
+    ```
+
+## Using the Plugin
+
+### Plugin Features
+
+- **Start Scan**: Click the "Run" button in the action bar to start scanning for vulnerabilities in the components of the current project.
+- **Stop Scan**: Click the "Stop" button in the action bar to stop the ongoing scan for vulnerabilities in the current project.
+- **Clear Scan Results**: Click the "Clean" button in the action bar to clear the scan results of the current project.
+- **Connection Configuration**: Click the "Test" button in the action bar to configure the platform URL and Token information. Click the "Test Connection" button to verify if the connection configuration is correct. Once the connection is successful, you can start scanning.
+- **Settings**: Click the "Setting" button in the action bar to view the settings related to OpenSCA Xcheck.
+- **Instructions**: Click the "Instructions" button in the action bar to view the user manual for OpenSCA Xcheck.
+- **See More**: Click the "See more" button in the action bar to visit [opensca.xmirror.cn](https://opensca.xmirror.cn) for more information about OpenSCA Xcheck.
+
+![xcheck_function](https://opensca.xmirror.cn/docs/img/vscode_02.jpg)
+
+### Plugin Execution Process
+
+![xcheck_flow](https://opensca.xmirror.cn/docs/assets/img/xcheck_process.7083b869.jpg)
+
+### Running a Scan
+
+Click on OpenSCA Xcheck to open the OpenSCA window. First, configure the server parameters in the configuration interface (refer to: Plugin Features - Settings), then click “Run” in the OpenSCA window (refer to: Plugin Features - Start Scan).
+
+# JetBrains IDEs
+
+## Installing the Plugin
+
+- **Method 1**: Install from the [JetBrains Plugin Marketplace](https://plugins.jetbrains.com/plugin/18246-opensca-xcheck) (Recommended)
+
+    For example, in IntelliJ IDEA: go to `File | Settings | Plugins | Marketplace`, search for "OpenSCA Xcheck" in the search box, and click "Install".
+    
+    ![xcheck_market](https://opensca.xmirror.cn/docs/img/xcheck_marketplace.jpg)
+
+- **Method 2**: Download the plugin from the [OpenSCA Platform](https://opensca.xmirror.cn/pages/plug-in) and install it manually
+
+    For example, in IntelliJ IDEA: drag the downloaded plugin package into the IDE.
+
+- **Method 3**: [Download the source code](https://github.com/XmirrorSecurity/OpenSCA-intellij-plugin) and compile it yourself
+
+    Open the downloaded source code in IntelliJ IDEA. Configure the runtime environment: `JDK11`. After Gradle imports dependencies and plugins, execute the `buildPlugin` task of the `intellij` plugin in Gradle. The built package will be located in the `build/distributions` directory of the project. Drag this package into the IDE to install it.
+
+## Using the Plugin
+
+### Plugin Features
+
+- **Configuration**: Click `File | Settings | Other Settings | OpenSCA Setting` or click the `Setting` button in the OpenSCA window to configure the server URL and Token in the configuration interface.
+- **Test Connection**: After configuring the server URL and Token in the OpenSCA configuration interface, click the `Test Connection` button to verify if the URL and Token are valid.
+- **Run**: Click the `Run` button in the OpenSCA window to perform a code assessment on the current project.
+- **Stop**: If a code assessment is ongoing for the current project, the `Stop` button will be enabled. Click the `Stop` button to end the current assessment task.
+- **Clear**: If the Xcheck sub-window in the OpenSCA window already has assessment results, click the `Clean` button to clear all results in the Xcheck sub-window.
+
+![xcheck_function](https://opensca.xmirror.cn/docs/img/xcheck_function.jpg)
+
+### Plugin Execution Process
+
+![xcheck_flow](https://opensca.xmirror.cn/docs/img/xcheck_process.jpg)
+
+### Running a Scan
+
+Click `View > Tool Windows > OpenSCA` to open the OpenSCA window. First, configure the server parameters in the OpenSCA configuration interface (refer to: Plugin Features - Configuration), then click the "Run" button in the OpenSCA window (refer to: Plugin Features - Run).
diff --git a/docs/README-zh-CN.md b/docs/README-zh-CN.md
@@ -8,7 +8,7 @@
     - [安装](./User_Guide/Installation-zh_CN.md)
     - [扫描](./User_Guide/Scanning/)
         - [依赖分析](./User_Guide/Scanning/Dependency_Analysis-zh_CN.md)
-        - [连接漏洞库](./User_Guide/Scanning/Connectiong_to_Vulnerability_Databases-zh_CN.md)
+        - [连接漏洞库](./User_Guide/Scanning/Vulnerability_Analysis-zh_CN.md)
     - [查看结果](./User_Guide/Viewing_Results-zh_CN.md)
     - [生成报告](./User_Guide/Generating_Reports/)
         - [SBOM](./User_Guide/Generating_Reports/SBOM-zh_CN.md)

diff --git a/docs/README.md b/docs/README.md
@@ -8,7 +8,7 @@
   - [Installation](./User_Guide/Installation.md)
   - [Scanning](./User_Guide/Scanning/)
     - [Dependency Analysis](./User_Guide/Scanning/Dependency_Analysis.md)
-    - [Connecting to Vulnerability Databases](./User_Guide/Scanning/Connectiong_to_Vulnerability_Databases.md)
+    - [Connecting to Vulnerability Databases](./User_Guide/Scanning/Vulnerability_Analysis.md)
   - [Viewing Results](./User_Guide/Viewing_Results.md)
   - [Generating Reports](./User_Guide/Generating_Reports/)
     - [Software Bill of Materials (SBOM)](./User_Guide/Generating_Reports/SBOM.md)

diff --git a/docs/Troubleshooting-zh_CN.md b/docs/Troubleshooting-zh_CN.md
@@ -0,0 +1 @@
+[返回目录](/docs/README-zh-CN.md) / [English](./Troubleshooting.md)
diff --git a/docs/Troubleshooting.md b/docs/Troubleshooting.md
@@ -0,0 +1 @@
+[Go Back](/docs/README.md) | [中文](./Troubleshooting-zh_CN.md)
diff --git a/docs/User_Guide/Configuration-and-Parameters-zh_CN.md b/docs/User_Guide/Configuration-and-Parameters-zh_CN.md
@@ -0,0 +1,123 @@
+[返回目录](/docs/README-zh-CN.md) | [English](./Configuration-and-Parameters.md)
+
+- [命令行参数](#命令行参数)
+- [配置文件说明](#配置文件说明)
+- [漏洞数据库配置示例](#漏洞数据库配置示例)
+- [漏洞数据库字段说明](#漏洞数据库字段说明)
+
+
+# 命令行参数
+
+| 参数      | 描述                                         | 使用示例                 |
+| --------- | -------------------------------------------- | ------------------------ |
+| `config`  | 指定配置文件路径                             | `-config config.json`    |
+| `path`    | 指定检测项目路径, 支持 http(s)/ftp/file 协议 | `-path ./foo`            |
+| `out`     | 根据后缀生成报告                             | `-out out.json,out.html` |
+| `log`     | 指定日志文件路径                             | `-log my_log.txt`        |
+| `token`   | 云端服务`token`                              | `-token xxx`             |
+| `proj`    | saas项目`token`                              | `-proj xxx`              |
+| `version` | 显示版本信息                                 | `-version`               |
+| `help`    | 显示帮助信息                                 | `-help`                  |
+
+# 配置文件说明
+
+配置文件使用 `json` 格式，支持以下字段: 
+> 默认会从目标检测路径中查找配置文件, 否则使用[默认配置文件](/config.json)。 可通过 `-config` 参数指定配置文件路径。
+
+- `path`: `String` 检测目标路径, 支持 http(s)/ftp/file 协议
+- `out`: `String` 报告输出路径, 通过后缀名识别文件类型, 支持 html/json/xml/csv/sqlite/cdx/spdx/swid/dsdx
+- `optional`: `Object` 可选配置项
+  - `ui`: `Boolean` 是否启用交互式界面, 默认为 `false`
+  - `dedup`: `Boolean` 是否启用组件去重(相同组件仅保留一条记录，组件路径合并), 默认为 `false`
+  - `dir`: `Boolean` 是否仅检测目录(跳过压缩包), 默认为 `false`
+  - `vuln`: `Boolean` 是否仅保留漏洞组件, 默认为 `false`
+  - `progress`: `Boolean` 是否显示进度条, 默认为 `true`
+  - `dev`: `Boolean` 是否保留开发组件, 默认为 `true`
+  - `tls`: `Boolean` 开启 TLS 证书验证, 默认为 `false`
+  - `proxy`: `String` 代理地址, 默认为空
+- `repo`: `Object` 组件仓库配置
+  - `maven`: `Array` maven 镜像/私服仓库配置
+    - `url`: `String` 仓库地址
+    - `user`: `String` 用户名
+    - `pass`: `String` 密码
+  - `npm`: `Array` npm 镜像/私服仓库配置
+    - `url`: `String` 仓库地址
+    - `user`: `String` 用户名
+    - `pass`: `String` 密码  
+  - `composer`: `Array` composer 镜像/私服仓库配置
+    - `url`: `String` 仓库地址
+    - `user`: `String` 用户名
+    - `pass`: `String` 密码
+- `origin`: `Object` 漏洞数据源配置
+  - `url`: `String` 漏洞数据源地址
+  - `token`: `String` 云端漏洞数据库个人访问令牌
+  - `proj`: `String` 项目访问令牌, 若置空则同步结果至"快速检测", 若无此字段(注释或删除)则不将结果同步至 OpenSCA SaaS
+  - `json`: `String` JSON 格式漏洞数据库路径
+  - `mysql`: `Object` MySQL 数据库漏洞数据源配置
+    - `dsn`: `String` 数据库连接字符串
+    - `table`: `String` 数据表名
+  - `sqlite`: `Object` SQLite 数据库漏洞数据源配置
+    - `dsn`: `String` 数据库连接字符串
+    - `table`: `String` 数据表名
+
+# 漏洞数据库配置示例
+
+```json
+{
+  // ...
+  "origin": {
+    // json 文件
+    "json": "vuln-db.json",
+    // MySQL
+    "mysql": {
+      // user:password@tcp(ip:port)/dbname
+      "dns": "opensca:opensca@tcp(3306:127.0.0.1)/opensca",
+      "table": "vuln"
+    }
+    "sqlite": {
+      "dns": "vuln.db",
+      "table": "vuln"
+    }
+  }
+
+}
+```
+
+# 漏洞数据库字段说明
+
+| 字段                | 描述                              | 是否必填 |
+| :------------------ | :-------------------------------- | :------- |
+| `vendor`            | 组件厂商                          | 否       |
+| `product`           | 组件名                            | 是       |
+| `version`           | 漏洞影响版本                      | 是       |
+| `language`          | 组件语言                          | 是       |
+| `name`              | 漏洞名                            | 否       |
+| `id`                | 自定义编号                        | 是       |
+| `cve_id`            | cve 编号                          | 否       |
+| `cnnvd_id`          | cnnvd 编号                        | 否       |
+| `cnvd_id`           | cnvd 编号                         | 否       |
+| `cwe_id`            | cwe 编号                          | 否       |
+| `description`       | 漏洞描述                          | 否       |
+| `description_en`    | 漏洞英文描述                      | 否       |
+| `suggestion`        | 漏洞修复建议                      | 否       |
+| `attack_type`       | 攻击方式                          | 否       |
+| `release_date`      | 漏洞发布日期                      | 否       |
+| `security_level_id` | 漏洞风险评级   | 否       |
+| `exploit_level_id`  | 漏洞利用评级 | 否       |
+
+- `language` 可选值: `java` `javascript` `golang` `rust` `php` `ruby` `python`
+- `version` 描述可使用以下格式:
+  | 符号          | 描述 (`x`为检出的组件版本)        |
+  | ------------- | -------------------------------- |
+  | `[a,b]`       | `a<=x<=b`                        |
+  | `(a,b)`       | `a<x<b`                          |
+  | `[a,b)`       | `a<=x<b`                         |
+  | `(a,b]`       | `a<x<=b`                         |
+  | `(0,b)`       | `x<b`                            |
+  | `(a,)`        | `x>a`                            |
+  | `{a,b,c,...}` | `x=a` 或 `x=b` 或 `x=c` 或 `...` |
+  > 同时位于多个范围需要用`||`连接，例如: `[a,b)||(b,c]`代表`a<=x<b`或`b<x<=c`，即`a<=x<=c`且`x!=b`
+  > 
+  > 也可以区间和集合混用: `(0,b)||{c,d}||[e,)`代表`x<b`或`x=c`或`x=d`或`x>=e`
+- `security_level_id` 可选值: `1` `2` `3` `4`, 分别对应严重、高危、中危、低危
+- `exploit_level_id` 可选值 `0`:不可利用 `1`:可利用
diff --git a/...ser_Guide/Parameter_Explanations-zh_CN.md → ...ser_Guide/Configuration-and-Parameters.md b/...ser_Guide/Parameter_Explanations-zh_CN.md → ...ser_Guide/Configuration-and-Parameters.md
diff --git a/docs/User_Guide/Docker-zh_CN.md b/docs/User_Guide/Docker-zh_CN.md
@@ -0,0 +1 @@
+[返回目录](/docs/README-zh-CN.md) / [English](./Docker.md)
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		[返回目录](/docs/README-zh-CN.md) / [English](./Troubleshooting.md)
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		[Go Back](/docs/README.md) \| [中文](./Troubleshooting-zh_CN.md)