Merge pull request #344 from XmirrorSecurity/codex/docs-config-ignore-patterns

docs: document config ignore patterns

Author: cyberchen1995

.github/README.md

@@ -26,6 +26,7 @@ English|[中文](../README.md)
   - [Method 4: Build from source](#method-4-build-from-source)
 - [Use OpenSCA](#use-opensca)
   - [Parameters](#parameters)
+  - [Ignore Paths in Configuration](#ignore-paths-in-configuration)
   - [Report Formats](#report-formats)
   - [Sample](#sample)
     - [Scan \& Report via Docker Container](#scan--report-via-docker-container)
@@ -149,6 +150,22 @@ If no path of configuration file is set, the following ones will be checked:
   2. `opensca_config.json` under the user directory
   3. `config.json` under `opensca-cli` directory
 
+### Ignore Paths in Configuration
+
+Use `optional.ignore` in the configuration file to skip files or directories during scanning. OpenSCA only reads ignore rules from the current configuration file and does not automatically load the project's `.gitignore`. The rules are compatible with common `.gitignore` syntax, including directory matches, wildcards, and `!` negation.
+
+```json
+{
+  "optional": {
+    "ignore": [
+      "JarCollection/",
+      "*.jar",
+      "!libs/keep.jar"
+    ]
+  }
+}
+```
+
 From v3.0.0, `url` has been put in the configuration file. The default set goes to our cloud vulnerability database. Other online database in accordance with our database structure can also be set through configuration file.  
 
 Using previous versions to connect the cloud databse will still need the setting of `url`, which could be done via both CMD and configuration file. Example: `-url https://opensca.xmirror.cn`

README.md

@@ -23,6 +23,7 @@
   - [方式 4: 从源码构建](#方式-4-从源码构建)
 - [使用说明](#使用说明)
   - [参数说明](#参数说明)
+  - [配置文件忽略路径](#配置文件忽略路径)
   - [报告格式](#报告格式)
   - [使用样例](#使用样例)
   - [漏洞库文件格式](#漏洞库文件格式)
@@ -153,6 +154,22 @@ v3.0.2开始，OpenSCA-cli可以通过proj参数向OpenSCA SaaS同步检出结
 2. 用户目录下的`opensca_config.json`
 3. `opensca-cli`目录下的`config.json`
 
+### 配置文件忽略路径
+
+可在配置文件的 `optional.ignore` 中设置需要跳过的文件或目录。该字段只读取当前配置文件中的规则，不会自动读取项目中的 `.gitignore` 文件；规则语法兼容常用 `.gitignore` 写法，包括目录匹配、通配符和 `!` 反选。
+
+```json
+{
+  "optional": {
+    "ignore": [
+      "JarCollection/",
+      "*.jar",
+      "!libs/keep.jar"
+    ]
+  }
+}
+```
+
 ### 报告格式
 
 `out` 参数支持范围如下：

docs/README-zh-CN.md

@@ -13,12 +13,12 @@
     - [生成报告](./User_Guide/Generating_Reports/)
         - [SBOM](./User_Guide/Generating_Reports/SBOM-zh_CN.md)
         - [检测报告](./User_Guide/Generating_Reports/Reports-zh_CN.md)
-    - [参数说明](./User_Guide/Parameter_Explanations-zh_CN.md)
+    - [配置与参数说明](./User_Guide/Configuration-and-Parameters-zh_CN.md)
     - [Docker](./User_Guide/Docker-zh_CN.md)
 - [集成配置](./Integrations/)
     - [IDE 插件](./Integrations/IDE_Plugins-zh_CN.md)
     - [CI/CD](./Integrations/CICD-zh_CN.md)
 - 开发者指南
     - [贡献指南](./Contributing_Guideline-v1.0-zh_CN.md)
-    - [代码规范](./Code_Standards-zh_CN.md)
-- [常见问题](./Troubleshooting-zh_CN.md)
+    - [代码规范](./Code_Standard-zh_CN.md)
+- [常见问题](./Troubleshooting-zh_CN.md)

docs/README.md

@@ -13,12 +13,12 @@
   - [Generating Reports](./User_Guide/Generating_Reports/)
     - [Software Bill of Materials (SBOM)](./User_Guide/Generating_Reports/SBOM.md)
     - [Detection Reports](./User_Guide/Generating_Reports/Reports.md)
-  - [Parameter Explanations](./User_Guide/Parameter_Explanations.md)
+  - [Configuration and Parameters](./User_Guide/Configuration-and-Parameters.md)
   - [Docker](./User_Guide/Docker.md)
 - [Integrations](./Integrations/)
   - [IDE Plugins](./Integrations/IDE_Plugins.md)
   - [CI/CD](./Integrations/CICD.md)
 - Developer Guide
   - [Contribution Guide](./Contributing_Guideline-v1.0.md)
   - [Code Standard](./Code_Standard.md)
-- [Troubleshooting](./Troubleshooting.md)
+- [Troubleshooting](./Troubleshooting.md)

docs/User_Guide/Configuration-and-Parameters-zh_CN.md

@@ -2,6 +2,7 @@
 
 - [命令行参数](#命令行参数)
 - [配置文件说明](#配置文件说明)
+- [忽略路径配置示例](#忽略路径配置示例)
 - [漏洞数据库配置示例](#漏洞数据库配置示例)
 - [漏洞数据库字段说明](#漏洞数据库字段说明)
 
@@ -35,6 +36,7 @@
   - `dev`: `Boolean` 是否保留开发组件, 默认为 `true`
   - `tls`: `Boolean` 开启 TLS 证书验证, 默认为 `false`
   - `proxy`: `String` 代理地址, 默认为空
+  - `ignore`: `Array<String>` 扫描时忽略的路径规则, 默认为空。仅读取当前配置文件中的规则, 不会自动读取项目 `.gitignore`; 规则语法兼容常用 `.gitignore` 写法, 包括目录匹配、通配符和 `!` 反选
 - `repo`: `Object` 组件仓库配置
   - `maven`: `Array` maven 镜像/私服仓库配置
     - `url`: `String` 仓库地址
@@ -60,6 +62,24 @@
     - `dsn`: `String` 数据库连接字符串
     - `table`: `String` 数据表名
 
+# 忽略路径配置示例
+
+如需跳过测试依赖、临时目录或特定压缩包, 可在 `optional.ignore` 中配置忽略规则:
+
+```json
+{
+  "optional": {
+    "ignore": [
+      "JarCollection/",
+      "*.jar",
+      "!libs/keep.jar"
+    ]
+  }
+}
+```
+
+上例会跳过 `JarCollection/` 目录及所有 `.jar` 文件, 但保留 `libs/keep.jar`。该配置只影响 OpenSCA 扫描过程, 不会修改项目文件。
+
 # 漏洞数据库配置示例
 
 ```json
@@ -120,4 +140,4 @@
   > 
   > 也可以区间和集合混用: `(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`:可利用
+- `exploit_level_id` 可选值 `0`:不可利用 `1`:可利用

docs/User_Guide/Configuration-and-Parameters.md

@@ -0,0 +1,55 @@
+[Back to Contents](/docs/README.md) | [简体中文](./Configuration-and-Parameters-zh_CN.md)
+
+- [Command-line Parameters](#command-line-parameters)
+- [Configuration File](#configuration-file)
+- [Ignore Path Configuration](#ignore-path-configuration)
+
+# Command-line Parameters
+
+| Parameter | Description | Example |
+| --------- | ----------- | ------- |
+| `config` | Set the configuration file path | `-config config.json` |
+| `path` | Set the target path. HTTP(S), FTP, and file paths are supported | `-path ./foo` |
+| `out` | Set report output paths. File types are detected by suffix | `-out out.json,out.html` |
+| `log` | Set the log file path | `-log my_log.txt` |
+| `token` | Cloud service token | `-token xxx` |
+| `proj` | SaaS project token | `-proj xxx` |
+| `version` | Print version information | `-version` |
+| `help` | Print help information | `-help` |
+
+# Configuration File
+
+The configuration file uses JSON syntax and supports the following top-level fields:
+
+- `path`: `String` target path. HTTP(S), FTP, and file paths are supported.
+- `out`: `String` report output paths. Supported suffixes include html/json/xml/csv/sqlite/cdx/spdx/swid/dsdx.
+- `optional`: `Object` optional scanning settings.
+  - `ui`: `Boolean` enable the interactive UI. Default: `false`.
+  - `dedup`: `Boolean` deduplicate identical components and merge paths. Default: `false`.
+  - `dir`: `Boolean` scan directories only and skip archives. Default: `false`.
+  - `vuln`: `Boolean` keep only vulnerable components. Default: `false`.
+  - `progress`: `Boolean` show the progress bar. Default: `true`.
+  - `dev`: `Boolean` keep development dependencies. Default: `true`.
+  - `tls`: `Boolean` enable TLS certificate verification. Default: `false`.
+  - `proxy`: `String` HTTP proxy address. Default: empty.
+  - `ignore`: `Array<String>` path rules ignored during scanning. Default: empty. OpenSCA only reads these rules from the current configuration file and does not automatically load the project's `.gitignore`. The syntax is compatible with common `.gitignore` rules, including directory matches, wildcards, and `!` negation.
+- `repo`: `Object` component repository settings for Maven, npm, and Composer.
+- `origin`: `Object` vulnerability database settings.
+
+# Ignore Path Configuration
+
+Use `optional.ignore` to skip test dependencies, temporary directories, or specific archives:
+
+```json
+{
+  "optional": {
+    "ignore": [
+      "JarCollection/",
+      "*.jar",
+      "!libs/keep.jar"
+    ]
+  }
+}
+```
+
+The example above skips `JarCollection/` and all `.jar` files, but keeps `libs/keep.jar`. Ignore rules only affect OpenSCA scanning and do not modify project files.