Metadata-Version: 2.4
Name: quietsec
Version: 0.3.3
Summary: Python 静态安全扫描：29 条规则覆盖 OWASP Top 10，输出可直接交付客户的 HTML 审计报告
Author: quietsec contributors
License-Expression: MIT
Keywords: security,static-analysis,sast,linter,owasp,cwe,code-review,audit,sarif
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: ca
Requires-Dist: certifi; extra == "ca"
Dynamic: license-file

# quietsec

**Python 代码的静态安全扫描。29 条规则覆盖 OWASP Top 10，输出一份能直接交给客户和老板的 HTML 审计报告。**

零依赖 · 不执行你的代码 · 不联网 · 可无限次跑

```bash
pip install quietsec
quietsec ./你的项目 --format html -o 审计报告.html
```

打开 `审计报告.html`，你会看到：安全评分、OWASP 覆盖矩阵、逐条定位到 `文件:行号` 的问题、命中行高亮的上下文代码、以及每条的修法。

---

## 为什么不是又一个 Bandit

Bandit 会给你 200 条告警，然后你得自己逐条判断哪些是真的。
quietsec 的设计目标相反：**宁可漏报，不给你噪音**。

在真实项目上实测（744 个 Python 文件）：

| | 告警数 | 人工核实为真 | 准确率 |
|---|---|---|---|
| quietsec（默认规则集） | 11 | 10 | **91%** |
| 同类工具通常 | 数百 | — | 需要人工筛 |

那唯一的一条误报我当天就改掉了规则。

**代价我也说清楚**：它查不出跨函数的数据流。`x = request.args["x"]`
传给别的函数后再进 SQL，这条链断在函数边界，它看不见。
所以别把它当 Semgrep 用——它的强项是**快、静、出报告**，不是全面。

---

## 装完能干什么

### 1. 出一份给客户的审计报告

```bash
quietsec ./项目 --format html -o 报告.html \
    --client "某某科技" --auditor "安全团队"
```

单文件 HTML，无 CDN、无脚本、无外部字体。内网隔离环境直接打开。
报告末尾有「检查方法与局限」一节，明确写了覆盖不到什么——
**说清楚边界的报告才可信**，这也是甲方愿意为它付钱的原因。

### 2. 出一份能照着改的清单

```bash
quietfix ./项目 -o 修复清单.md
```

按 P0（上线前必修）/ P1（本周）/ P2（可排队）分组，
每条带勾选框和**工作量评估**。同一条规则的多处问题合并在一个标题下，
你可以一次改完一类。

### 3. 接进 CI

```bash
# 有高危就不让合并
quietsec . --fail-on high

# 输出 SARIF，喂给 GitHub Code Scanning / VS Code
quietsec . --format sarif -o results.sarif
```

退出码：`0` 通过，`1` 达到阈值，`2` 参数或路径错误。

SARIF 输出里每个问题都带 CWE 编号和 `security-severity`，
GitHub 的安全面板能正确分级。

---

## 能查什么

| 类别 | 规则 |
|---|---|
| **注入** | SQL 注入、命令注入（`os.system` / `shell=True`）、`eval`/`exec`、模板注入（SSTI） |
| **凭证与加密** | 硬编码密钥、弱哈希、ECB 模式、固定 IV、关闭 TLS 校验、废弃 TLS 版本 |
| **认证配置** | JWT 不验签、CORS 通配符+凭证、`debug=True` 上线、开放重定向 |
| **数据处理** | pickle/YAML 不安全反序列化、临时文件竞态 |
| **代码质量** | 可变默认参数、裸 `except`、文件编码、请求无超时 |

每条规则都映射到 OWASP Top 10 (2021) 和 CWE。

可选规则（默认关闭，`--enable` 开启）：
`silent-except`（吞异常）、`assert-validation`（assert 做校验）、`long-function`

**默认关闭不是没做完，是故意的**：这三条在正规库代码上误报率 100%，
但在业务代码里可能很关键。开启方式：

```bash
quietsec ./业务代码 --enable silent-except
```

---

## 作为库用

```python
from quietsec import scan_text, scan_repo, Finding

# 扫一段代码
findings = scan_text("app.py", source_code)
for f in findings:
    print(f"{f.file}:{f.line}  {f.rule}  {f.severity}")
    print(f"  {f.message}")
    print(f"  建议: {f.suggestion}")
    print(f"  指纹: {f.fingerprint}")   # 跨行号稳定，可做增量对比

# 扫整个仓库
findings, scanned_files, stats = scan_repo("./project", max_files=2000)
```

`Finding.fingerprint` 是 `文件+规则+证据` 的哈希，
代码行号变了指纹不变——适合做「只推新增问题」的增量流程。

---

## 抑制误报

在行末加注释，按行生效：

```python
token = random.randint(0, 10**9)        # noqa
token = random.randint(0, 10**9)        # noqa: weak-random
api_key = "sk-test-..."                 # noqa: hardcoded-secret
```

`# noqa` 压制该行全部，`# noqa: rule-a,rule-b` 只压制指定的。

---

## 常见问题

**会不会执行我的代码？**
不会。它只用 `ast` 解析语法树，跟编译器的前端一样。你可以拿一个有
`rm -rf /` 的文件试，它只会告诉你第几行是危险调用。

**会联网吗？**
默认完全不联网。只有你显式加 `--ai` 才会调外部 API（需要自己的 key）。

**支持 Python 2 吗？**
不支持。遇到纯 Python 2 语法会报 `syntax-error`。

**为什么不出 Java / Go / JS 版本？**
AST 层要整个重写。等 Python 版有真实使用量了再说。

**报告能给客户看吗？**
可以，这正是它的设计目标。但请如实告知对方这是自动化静态分析的结果，
不是渗透测试，也不是安全承诺书。

---

## 环境

Python 3.9+，零第三方依赖。
`pip install quietsec[ca]` 会顺带装 `certifi`（仅在 `--ai` 模式下用得到）。

## 卸载

```bash
pip uninstall quietsec
```

不写任何配置文件，不在项目目录留东西。

---

## License

MIT

---

## 联系

工具本身免费开源，可商用、可改、可再分发。

需要人工逐条复核、出一份能直接交给客户的审计报告：
`476512478@qq.com`

服务内容与价格见 `sales/服务介绍.md`、`sales/报价单.md`。

---

*这个工具是我在真实项目上一条规则一条规则调出来的。*
*每条规则都有正反两面的测试：该报的必须报，不该报的必须不报。*
*当前 179 个测试用例。*
