AngusSecurity 是一个应用安全检测与治理平台，一次检查，一份问题列表。勾选代码、密钥、依赖、许可证和镜像里要查的项，门禁用通过、未通过、无法判定、跳过决定能不能合并或发布。数据留在这次安装里。
解决的主要问题
- 合并前不知道这次能不能过。高危要到发布之后，才在另一份报告里被看见。合并前对目标分支做一次检查，门禁用通过、未通过、无法判定、跳过说明这次能不能合。任务还在运行，或门禁仍在计算时，空列表不能当成通过。
- 代码、密钥、依赖、许可证和镜像各有一份结果，验收时对不上同一行。同一次检查写成一份问题列表，再生成一份报告。页面、命令行和流水线写入的是这一份。密钥片段在列表里保持打码，不把原文抄进工单。
- 项目要交付时，漏洞、许可证和代码质量散在不同报告里。对这次发布候选做一次检查，把这些写进同一份报告。报告是生成那一刻的快照，后面的新检查不会改写它。代码质量在质量列，不计入安全门禁。许可证另有一道门。
- 代码和制品要先传出去，才能在外面做检查。检查在这次安装里跑，结果和报告留在这里。交付物不用先交给外部扫描服务。
主要功能
登录后先看到「概览」，用来看当前风险、检查进展，以及还没处理完的安全问题。
一次检查勾什么。「新建检查」在概览和检查列表上，不单独占菜单。向导四步是目标、能力、高级、确认，最后点「开始检查」。看不到这个按钮时，账号多半是只读，需要开发者或以上。删除一次检查需要分析师或管理员。
| 你勾选的 | 检查什么 | 谁来跑 | 会不会卡住安全门禁 |
|---|---|---|---|
| 代码安全 | 源码里的注入、XSS、不安全 API | OpenGrep | 会 |
| 密钥检查 | Token、私钥、连接串 | Gitleaks | 会 |
| 依赖/制品漏洞 | 依赖、安装包和镜像里的已知漏洞。结果页这张卡片叫「安全漏洞」 | Trivy | 会 |
| 许可证合规 | 对照策略里的名单和分发场景 | Trivy | 另有许可证门禁 |
| 代码质量 | 按语言看缺陷和坏味道 | SpotBugs、PMD、ESLint、Ruff、staticcheck、detekt | 只出现在质量列 |
代码安全是这些规则在单个文件里能看到的命中。不要把它说成跨文件数据流已经证明可利用。密钥检查给出的是规则和打码后的片段，不是把密钥拿到供应商那里验证现在还能不能用。某一项旁边出现「引擎未就绪」时，先到「工具」把对应程序准备好。仍然强制提交的话，任务往往会以结果不完整结束，门禁是无法判定。
可以检查什么。页面上可以直接发起四种。上传文件或文件夹：默认最多 5000 个文件、合计 200MB，适合一小段代码或补丁，还不想交出仓库读权限。Git 仓库：填远程地址，再指定分支、Tag 或某一次提交。制品：填一条能直接下载的 http(s) 地址，不是 Maven 坐标。容器镜像：查镜像里的包漏洞和许可证。
浏览器上传成功后，任务详情的目标类型写成「本地目录」。文件已经落到服务器工作区，不是你另外指定的一台机器上的路径。服务器上已经存在的单个文件或目录，从命令行发起，路径必须落在 AngusSecurity 这台机器允许读取的目录里。
私有仓库在高级里选一条已经保存的凭据，类型是 Git Token 或 Git SSH。也可以临时填访问令牌，它会盖过已保存的那条。公开仓库可以不填。凭据在「系统」里维护，不要把令牌写进流水线脚本的正文。
浅克隆深度默认是 1：只取所选分支最近一次提交，查的是当前这些文件。更早提交里出现过、后来删掉的密钥，不会出现在这次结果里。要追历史，把深度改成 0 再跑一次。目标是某一次提交哈希时必须填 0，否则那次提交可能不在这一次历史里，克隆会找不到它，或者扫到别的内容。地址不通、令牌过期或权限不够，会在准备中失败。
跑起来之后看哪一层。状态按这个顺序变化：待处理、准备中、运行中、归一化中，然后结束。准备中是在克隆、下载或准备工作区，百分比很低。进入运行中后，百分比会先停住，等扫描程序开始返回才继续；全部返回后进入归一化中，这时在整理发现。只有一个扫描程序时，它一返回，百分比会一下子跳到接近完成。这是正常的，不是卡住后突然结束。列表或详情里还有未结束的任务时，页面大约每 2 秒刷新一次。浏览器切到别的标签后会暂停。任务还在跑时，门禁显示「计算中」。
结束时先看状态，再看门禁。
| 状态 | 怎么理解 |
|---|---|
| 已完成 | 你勾选的项目都有了可信结果。门禁仍可能是未通过 |
| 结果不完整 | 至少有一项没有得出可信结果，门禁多为无法判定。任务还在跑时不会出现这句 |
| 失败 | 这次没有跑完，详情里有原因 |
| 超时 | 超过了允许的时间 |
| 已取消 | 已取消。已经结束的任务不能再取消 |
已完成并且门禁是通过，才表示查完了、也没有超过阈值。结果不完整、失败、超时都不能当成没有问题。待处理、准备中、运行中通常可以取消。进入归一化之后，以按钮是否还能点为准。
打开一条任务，标题旁边是状态。能力卡片的顺序是：安全漏洞、许可证合规、密钥检查、代码安全、代码质量。每张卡片右上角是已完成、未完成、未执行或未调度。未执行表示勾选了，但这次目标用不上。未调度表示没有安排对应的扫描程序。引擎表用另一套词：成功、失败、未调度。镜像上的代码安全经常是卡片写未执行、引擎表写未调度，因为镜像里没有源码可查。卡片上的未完成，才是这项扫描程序失败了。标题上的失败，才是整次任务没跑完。
列表上的漏洞列只统计严重、高危、中危的安全问题，不含许可证和代码质量。许可证、质量、密钥各自一列。许可证和代码质量条数很多时，安全门禁仍可以是通过；许可证放不放行，看许可证自己的结论。
问题列表。严重度是严重、高危、中危、低危、信息、未知，并带位置和修复建议。确认是误报时，在某一行上点「抑制」，只对这一次检查生效。原来的那一行还在。弹出的是确认框，不单独填写原因或过期时间。勾选多行后可以批量抑制。抑制痕迹在「活动」里。看不到抑制按钮时，需要分析师或管理员。真实可利用的高危或严重，只是暂时没空修，应走告警，不要抑制。导出按当前筛选下载。当前筛选是代码质量或许可证时，不能导出 SARIF。
策略上的两道门。侧栏「策略」的页头是「策略中心」，页签是扫描策略和自定义许可证。它决定什么时候发起检查，以及超过哪一档算未通过。阈值只统计代码安全、密钥检查、依赖/制品漏洞。代码质量不进任何门禁。勾选许可证合规后，另外出现允许名单、禁止名单、分发场景和许可证门禁。分发场景有仅内部使用、SaaS、分发二进制、分发容器镜像，默认是分发二进制。许可证门禁三档是不参与门禁、不兼容时拒绝、无法判定也拒绝。它不用严重度。漏洞阈值和许可证门禁有一道未通过，任务的门禁结果就是未通过。由制品仓库发起的检查，会带上仓库自己的分发场景和许可证门禁，名单仍用这里的。
自定义许可证只影响本租户的目录：补一条目录里没有的标识，或改某个标识的类别。和内置标识同名时，以这里的类别为准。两边都没有的标识，类别是未识别。改了分发场景、名单或自定义许可证之后，已经完成的任务不会自动重算，需要重新检查。策略详情可以用已有任务的计数做一次模拟，不发起新扫描。
报告是当时的一份快照。侧栏「报告」的页头是「安全报告」。新的检查完成后，已经生成的报告不会自己更新。日常跟进走告警。报告适合里程碑、发版归档和抽查。页签是历史报告、模板、定时订阅。勾选两份历史报告后可以对比。生成向导依次是受众、范围、内容、品牌与交付、调度与投递。受众有管理层态势、研发修复、自定义。范围是全部资产（当前态）、时间范围或指定检查。格式是 HTML、PDF、CSV（ZIP）、JSON、SARIF。点生成之后，状态从排队中到生成中，然后是已就绪或失败。就绪后再下载或预览。看不到生成或下载时，需要分析师或管理员。
命令行是另一条入口，不是另一个扫描器。发行包里的命令名是angus-security，脚本在tools/bin/angus-security。它向服务创建或查询检查，检测程序跑在服务那一侧。环境变量是ANGUS_SECURITY_URL和ANGUS_SECURITY_TOKEN。没有--mode、没有--api-url参数，也没有把令牌写在命令行参数里的用法。--enable不传时，默认跑代码安全、密钥检查和依赖/制品漏洞。这条命令没有浏览器上传通道。--target-type DIRECTORY的路径是服务所在机器上的路径。
本机引擎是否健康，用tools/bin/doctor.sh，或打开页面上的「工具」。漏洞库过期时，默认任务仍可以是已完成，并多一条说明漏洞库年龄的发现。发版前在工具页确认库是新的，或执行tools/bin/update-trivy-db.sh。节点打开「过期即失败」后，任务改为结果不完整，门禁无法判定。
应用场景
高危是合并进默认分支之后，才在另一份报告里被看见。对目标分支勾代码安全和密钥检查，深度用快速，门禁用高危。浅克隆保持 1，不要把完整历史的密钥检查放进每一次合并请求。流水线里同一档写成
--enable sast,secret --fail-on high，并加上--wait。任务结束后先读门禁四个词，再决定这盏灯。任务还在运行中，或门禁仍是计算中时，空列表不能当成通过。镜像已经要进发布单，包漏洞还没有一份能引用的结果。勾依赖/制品漏洞。许可证名单要紧时再勾许可证合规。镜像上的代码安全经常是未执行，这不是源码已经查过。安装包填能直接下载的地址。任务必须是已完成。结果不完整不能当发版依据。发版前在「工具」确认漏洞库是新的，或先执行
tools/bin/update-trivy-db.sh。制品仓库入库时的拦截是另一道门，不要和这里的检查当成同一盏灯。跨仓库的问题和报告仍在这里看。验收要引用的是当时那一次，列表后来又多了新的检查。对这次发布候选再跑一次，深度用标准，并勾上依赖/制品漏洞。任务已完成之后，按这次检查生成报告。要进缺陷系统用 SARIF 或 JSON，要给人看用 HTML 或 PDF。这份报告是生成那一刻的快照。后面又有新的检查，它不会自己改写。
密钥命中被抄进工单时，片段还是原文。问题列表里的密钥片段保持打码。误报点「抑制」，范围只是这一次检查，原来的行还在。下一次检查不会因为这次点过抑制就消失。高危如果只是还没排进修复，走告警，不走抑制。
核心亮点
页面、命令行和流水线写入的是同一份问题列表。少做的那一步，是把三条扫描输出再对一次行号。误报点「抑制」，范围只是这一次检查，原来的行还在。下一次检查不会因为这次点过抑制就自动消失。高危只是还没排进修复，走告警，不走抑制。
退出码 0 不等于通过。
angus-security的退出码0包含门禁通过、跳过，以及当前实现下的无法判定。只有未通过才是退出码1。请求失败或--wait大约 12 分钟仍未结束，是退出码2。未知命令、缺参数或不支持的--format是3。--wait只把已完成、失败、已取消、超时当作结束，不会把结果不完整当作终态，于是可能一直等到超时。流水线要把「结果不可信」也判红，必须同时看任务状态和门禁四个词。跳过表示这次没有做判定，常见原因是某个程序未调度、这种对象用不上这项、或策略条件对不上。页面上的策略和命令行
--fail-on要设成同一档。策略是组织默认、定时和 Webhook 用的阈值。--fail-on是这一条流水线步骤的判定，取值是严重、高危、中危、低危。组织策略是高危，某个仓库的命令却不传--fail-on时，页面上会是未通过，流水线退出码仍是 0。命令行没有never这个取值。JUnit 格式里，只有门禁未通过才记一条 failure。质量列不计入安全门禁。少做的那一步，是把坏味道和质量告警算进同一盏合并红灯。质量条数可以很多，安全门禁仍按代码、密钥和依赖的那一档计算。许可证另算，不跟严重度混在一个阈值里。
镜像上没跑代码安全，不是查过了。卡片未执行、引擎表未调度，原因是没有源码。要查的是包漏洞和许可证。卡片未完成才表示这项程序失败，这时整次任务常常是结果不完整，门禁无法判定，就按拦住处理。
部署方式
本包安装 AngusSecurity 1.0.0，并带上门户。浏览器先打开门户，再打开本产品。有 Docker 时走安装向导，默认是 Docker Compose。没有 Docker，走主机 ZIP。安装机不能访问公网，走离线安装。Kubernetes 的 Helm 目前是预览，不要当成生产安装。
生产用 Linux x86_64。试用可以用 macOS。docker compose version要能打出版本号。macOS 用当前登录用户跑向导，不要加sudo。Linux 要装到/opt/angus，先把目录所有者改成当前用户。
80 端口空闲。要 HTTPS 时 443 也空闲。8809和8801是应用自己的端口，反向代理会转发，不必对公网开放。gm.<你的域名>和security.<你的域名>解析到这台机器。安装包从https://repo.anguskit.com的 raw-public 下载。解压目录是AngusSecurity-1.0.0。
unzip<安装包>.zipcdAngusSecurity-1.0.0 ./install.shWindows 在 Docker Desktop 里执行.\install.bat。向导提示是英文。
| 向导提示 | 你输入什么 | 它决定什么 |
|---|---|---|
Install mode | 回车 | Docker Compose。没有 Docker 时改用主机 ZIP |
Access | 输入2 | 自带反向代理和子域名。回车留在按端口访问 |
| 反向代理 | 回车 | Caddy。Let’s Encrypt 只能配 Caddy |
| 证书 | 必须输入数字，没有默认 | 1已有 PEM，2自签，3Let’s Encrypt，4只用 HTTP |
| 数据库 | 回车 | Compose 在本机起 MySQL 8 |
| 安装目录 | 回车 | 当前解压目录，即$ANGUS_HOME |
| 根域名 | example.com这种根域 | 填security.example.com会多拼一层。IP 或localhost会停下 |
管理员密码至少 8 位。不要沿用向导给出的公开默认数据库口令。数据目录只在第一次创建时采用这个口令。之后只改配置文件、不改库里已经存下的口令，应用会连不上。默认字符串不写在这里。
证书选1、2或3，打开https://gm.<你的域名>/，再打开https://security.<你的域名>/。选4则两边都是http://。自签时浏览器会警告。当前安装包在选 Let’s Encrypt 时，仍会为七个产品子域申请证书，即使这台机器只装了本产品和门户。那七个名字都要解析到本机，或者改用通配符证书。只走 HTTP 时选4，不受这条限制。
成功是日志末尾两行：doctor: OK和Install finished.日志在$ANGUS_HOME/logs/install.log。之后执行./bin/angusctl.sh doctor。装完控制台还要看「工具」里的检查程序是否就绪。未就绪就发起检查，结果很容易是不完整。
MCP 接入
经网关的地址是https://<gateway-host>/security/mcp。私有化没有产品前缀时，改为https://<security-host>/mcp。应用默认端口是1811，经反向代理访问时不必把这个端口暴露到公网。令牌放进ANGUS_SECURITY_TOKEN，请求头是Authorization: Bearer。令牌在头像「我的」里签发，这个页面不在侧栏。必须是本门户的用户访问令牌。别的产品的令牌，以及以repod_开头的令牌，会得到 401，响应里没有工具列表。不要把令牌写进仓库。
当前发行配置里，未设置环境变量时端点是打开的，写开关也是打开的。ANGUS_MCP_ENABLED=false时进程没有/mcp，控制台、命令行和已有检查不受影响。写开关设成false之后，工具列表里没有security_scan和security_create_report。每个账号每分钟最多调用 30 次。
只支持 stdio 的宿主，用@anguskit/mcp转发到同一个地址。这个进程读的环境变量名是ANGUS_TOKEN和ANGUS_BASE_URL，与 HTTP 配置里的ANGUS_SECURITY_TOKEN不是同一个名字。ANGUS_BASE_URL是网关根地址，不要带/security/mcp。默认 npm 源找不到这个包时，把源换成https://repo.anguskit.com/npm/npm-public/。
助手看到的数据和能做的操作与这个账号在控制台一致，不会扩大权限。只读账号的列表里没有security_scan。密钥片段保持掩码，不能要求揭密。security_scan的kind是git、image、artifact、files里的一种，一次只填一种目标，创建后立刻返回jobId。私有目标只填控制台里的凭据名称，不在对话里传令牌。分支用你说的或当前分支，不猜main。完成后用security_issues看这次结果。notScanned=true表示这项没跑。空列表不能说成目标安全。
security_list_jobs用来看检查是否跑完。状态不是COMPLETED或PARTIAL时，不能把计数说成没有问题。security_list_findings的列表不含代码片段。没有结果表示尚未检查，或筛选没有命中。security_explain_finding返回规则含义、修复建议和片段，密钥片段仍是掩码。助手应使用工具返回的完整 id，不要把 id 四舍五入或截断。
security_create_report只为一次已结束的检查生成报告。任务仍在运行时会拒绝，并且不会创建报告。调用后状态是PENDING，再用security_get_report看它是否变为READY。抑制、揭密、发布、分享和删除没有对应工具，这些留在控制台。
SDK 接入
官方 REST SDK 版本 1.0.0。Java 构件angus-security-sdk，包名cloud.xcan.angus.sdk.security。npm 是@anguskit/angus-security-sdk。PyPI 是angus-security-sdk。Go 模块是github.com/anguskit/angus-sdk-security。没有官方 NuGet 包。
认证头是Authorization: Bearer <access_token>。网关 Base URL 是https://bj-c1-prod-apis.anguskit.com/security。路径前缀/api/v1/**。冒烟请求是GET /api/v1/overview/risk。列问题是GET /api/v1/findings。字段以 API 参考里的 OpenAPI 为准。/innerapi不在官方 SDK 里。
SDK 调的是 REST。发起检查、等到结束、按退出码给流水线亮灯，用的是angus-security。两条不要写成同一条命令。SDK 读到的是任务状态和门禁字段。退出码0那一套映射只存在于命令行。
FAQ
任务一直停在准备中，能不能连续点重试？
先核对仓库地址和凭据有没有过期。公开仓库不要误选认证。不要连续重试，工作区磁盘会被占满。仓库很大时，把浅克隆深度调小。
依赖或镜像几乎没有漏洞，是不是已经干净？
先打开这次检查，看有没有勾上依赖/制品漏洞。扫目录时，目录里要有锁文件。查镜像要选容器镜像，不要选成普通目录。漏洞库过期时到「工具」看。按 CVE 查本机漏洞库，库里没有这条记录，只说明库里没有，不改写成目标没有漏洞。
退出码是 1，页面上这次检查却是已完成？
检查跑完了。退出码1表示门禁未通过。到问题列表里处理达到阈值的那一档。
从哪登录？
先开gm.<你的域名>，再开security.<你的域名>。不要把8809当成对外入口。
参考文章
- AngusSecurity 介绍
- AngusSecurity 检查任务
- AngusSecurity 策略与门禁
- AngusSecurity CLI 基础用法
- AngusSecurity 安装与部署
- 通过 MCP 连接 AngusSecurity
- AngusSecurity SDK 接入
- AngusSecurity 支持哪些主要功能
