guardlink (Bugb Technologies)

](https://www.npmjs.com/package/guardlink)   ](https://nodejs.org) 

存在于代码中的安全注释。代码更改时，您的威胁模型会更新。

此存储库由GuardLink保护。 跑 guardlink status . 查看12个资产、13个威胁和10个控制中的272个注释——由AI代理维护，在CI中验证。

// @asset PaymentService (#payments) -- "Handles card transactions"
// @threat SQL_Injection (#sqli) [critical] cwe:CWE-89

// @mitigates #payments against #sqli using #prepared-stmts
app.post('/charge', async (req, res) => {
  const result = await db.query('SELECT * FROM cards WHERE id = $1', [req.body.id]);
});

// @exposes #payments to #idor [P1] cwe:CWE-639 -- "No ownership check"
app.get('/receipts/:id', async (req, res) => {
  const receipt = await db.query('SELECT * FROM receipts WHERE id = $1', [req.params.id]);
});

______________________________________________________________________

安装

npm install -g guardlink

需要Node.js 18+。

手动安装

要从源代码安装，请执行以下操作：

# 1. Build the project
npm run build

# 2. Link globally
npm link

要卸载，请执行以下操作： npm unlink -g guardlink

快速开始

# Initialize in your project (detects your AI agent automatically)
guardlink init

# Let AI annotate your project - Launch a coding agent to add annotations
guardlink annotate [prompt] [--mode inline|external]

# Let your AI coding agent annotate, or write annotations manually
# Then validate
guardlink validate .

# See your security posture
guardlink status .

Assets:        3    Mitigations:  4
Threats:       8    Exposures:    6  (3 unmitigated)
Controls:      5    Coverage:     62%

# Generate a full threat model report
guardlink report .

# Interactive HTML dashboard
guardlink dashboard .

# AI threat analysis (STRIDE, DREAD, PASTA, etc.)
guardlink threat-report stride --claude-code

# Interactive TUI with slash commands
guardlink

______________________________________________________________________

演示视频


______________________________________________________________________

为什么选择GuardLink

威胁模型会腐烂。团队在项目开始时会进行一次会话，有人会创建一个Confluence页面，到下一个冲刺时它就会过时。SAST扫描程序会发现200件没有上下文的事情。笔测试报告存储在共享驱动器中。根本原因总是一样的： 安全知识存在于代码之外.

GuardLink从三个层面解决了这个问题：

1.代码中的注释。 安全决策是它们所描述的代码旁边的结构化注释。当开发人员编写参数化查询时， @mitigates #api against #sqli using #prepared-stmts 就在它上面。当代码发生变化时，注释就在那里进行更新。威胁模型 *是* 代码。

2.人工智能代理维护它。 GuardLink通过MCP和行为指令与AI编码代理集成。当您的代理编写路由处理程序时，它会添加 @exposes 和 @mitigates 自动注释。威胁模型能够自我维护，因为编写代码的东西也会编写安全上下文。

3.CI强制执行。 guardlink validate 由于语法错误而失败。 guardlink diff --fail-on-new 阻止引入未缓解暴露的PR。 guardlink sarif 导出到GitHub的安全选项卡。威胁模型变成了一个质量门，而不是一个复选框。

Developer writes code
       ↓
AI agent adds security annotations
       ↓
CI validates on every PR
       ↓
Team reviews security posture in the diff
       ↓
Threat model is always current, always enforced

______________________________________________________________________

AI代理集成

GuardLink为AI编码代理提供了MCP服务器和行为指令。之后 guardlink init，您的代理将安全注释视为类型安全——在编写与安全相关的代码时默认添加它们。

guardlink init 检测您的代理并配置两件事：

MCP服务器 --用于读取威胁模型、验证注释、建议注释和按关键字查询威胁的工具。在编写涉及api的代码之前，代理可以询问“什么威胁会影响#neneneba api？”。

行为指导 --注入代理指令文件（CLAUDE.md、.cursorules等）的规则，内容如下： *在编写处理路由、身份验证、数据库访问、文件I/O或外部服务的代码时，请添加GuardLink注释。*

支持的代理

MCP工具

资源： guardlink://model, guardlink://definitions, guardlink://config

______________________________________________________________________

命令

______________________________________________________________________

注释参考

GuardLink注释可以存在于任何语言的源代码注释中，也可以独立存在 .gal 文件夹。解析器支持 //, #, --, /* */, """ """，以及用于内联注释的25+注释样式，以及用于外部化文件的原始GAL行。

独立运行 .gal 文件，删除主机语言注释前缀。 // @exposes ... 成为 @exposes ....将定义保存在 .guardlink/definitions.*；使用 .gal 用于外部化关系注释的文件。使用 `@source file:

line: [symbol:]` 将以下注释指向实际代码位置。

定义（共享，在 .guardlink/definitions.js)

// @asset App.API (#api) -- "Express REST API serving mobile and web clients"
// @threat SQL_Injection (#sqli) [critical] cwe:CWE-89 -- "Unsanitized input reaches SQL query"
// @control Parameterized_Queries (#prepared-stmts) -- "All queries use bound parameters"

关系（在源文件中，代码旁边）

# @mitigates #api against #sqli using #prepared-stmts -- "All queries parameterized"
# @exposes #api to #xss [P1] cwe:CWE-79 -- "User bio rendered without escaping"
# @accepts #info-disclosure on #api -- "Health endpoint is intentionally public"
# @transfers #sqli from #api to #database -- "DB handles untrusted input"

外部关系（in .gal 文件）

@source file:src/auth/login.ts line:42 symbol:authenticate
@exposes #api to #xss [P1] cwe:CWE-79 -- "User bio rendered without escaping"
@audit #api -- "Review sanitization before release"
@comment -- "Same GAL syntax as inline comments, but without // or # prefixes"

数据流和架构

// @flow #api -> #database via "PostgreSQL wire protocol"
// @boundary #api  #cdn -- "TLS termination point"
// @handles pii on #api -- "Processes user email and address"
// @handles secrets on #auth -- "Manages JWT signing keys"

可操作的

// @audit #api by "PenTest Corp" on 2025-03-15 -- "Annual penetration test"
// @validates #input-validation on #api using "Jest integration tests"
// @assumes #api -- "Rate limiting handled by API gateway"
// @owns #api by "backend-team"

所有注释类型

严重程度： [critical]/[P0], [high]/[P1], [medium]/[P2], [low]/[P3]外部参考文献： cwe:CWE-89, capec:CAPEC-66, owasp:A03.

______________________________________________________________________

CI集成

GitHub操作

name: GuardLink
on: [pull_request]

jobs:
  guardlink:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 0 }

      - uses: actions/setup-node@v4
        with: { node-version: '20' }

      - run: npm install -g guardlink

      - name: Validate annotations
        run: guardlink validate .

      - name: Threat model diff
        run: guardlink diff --from origin/main --to HEAD

      - name: Export SARIF
        run: guardlink sarif . -o guardlink.sarif

      - uses: github/codeql-action/upload-sarif@v3
        with: { sarif_file: guardlink.sarif }

看 关于PR评论和SARIF上传的完整示例。

多代表CI

对于工作区设置，GuardLink提供了两个额外的工作流模板：一个是每个仓库工作流，在每次推送时生成报告JSON工件；另一个是工作区合并工作流，每周运行一次，将所有仓库合并到一个统一的仪表板中。看 CI设置指南 获取分步说明。

CI捕获什么

• 新路线，无注释： guardlink diff 显示“+1终点，0缓解措施”——团队看到了差距。
• 代理人正确注释： diff显示“+1资产，+2缓解措施，+1风险敞口（IDOR）”——团队评审。
• 控件已删除： 差异显示“-1缓解，+1未缓解暴露”-- --fail-on-new 阻止PR。

萨里夫

guardlink sarif 出口未缓解的风险敞口 @confirmed 结果为严重急性呼吸系统综合征2.1.0。上传到GitHub高级安全：未缓解 @exposes 按严重程度显示为警告或错误； @confirmed 可利用的发现显示为错误。

最重要的整合

GuardLink在两个方向上连接了威胁建模和渗透测试。

从威胁模型到渗透测试模板 — guardlink translate 阅读你的 @exposes 注释并生成针对您记录的特定威胁的CERT-X-GEN（CXG）渗透测试模板存根。使用任何代理后端运行它：

guardlink translate --claude-code
guardlink translate "focus on injection paths" --clipboard

从渗透测试结果返回到威胁模型 --将CXG扫描结果JSON文件放入 .guardlink/pentest-findings/.GuardLink会自动读取它们并：

• 将研究结果作为经验证据注入 guardlink threat-report 和AI分析
• 显示a 最重要的发现 部分在 guardlink dashboard
• 教导代理将扫描结果与 @exposes 注释

标记已验证的发现 --当渗透测试或扫描证明威胁可被利用时，添加 @confirmed 要关闭循环：

// @confirmed #sqli on App.API [critical] cwe:CWE-89 -- "CXG scan 2026-04: time-based blind SQLi on /login confirmed"

@confirmed 不同于 @exposes （假设）——它意味着真实的、经过验证的，而不是假阳性。

安全处理证据 --在中查找JSON文件最重要 .guardlink/pentest-findings/ 并在中生成模板 .guardlink/cxg-templates/ 通常包含从成功利用漏洞中捕获的实时令牌、JWT、凭证有效载荷和其他可回放材料。在对您关心的任何系统运行扫描之前，请将这些目录添加到存储库的忽略文件中。GuardLink还支持选择性手术编辑(guardlink config set redact-evidence true)适用于其合规状态不需要静态明文凭据的企业用户。请参阅 docs/handling-evidence.md 获取完整的操作指南。

______________________________________________________________________

多回购工作区

在微服务架构中，单个repo只具有部分安全性。 PaymentService 定义见 repo-payments，暴露在 repo-gateway，缓解 repo-auth-lib.GuardLink工作区链接这些存储库，因此威胁模型跨越了服务边界。

# Link three repos into a workspace
guardlink link-project ./payment-svc ./auth-lib ./api-gateway \
  --workspace acme-platform

# Each repo gets .guardlink/workspace.yaml + agent files updated with cross-repo context
# Agents now know about sibling services and use tag prefixes like #payment-svc.refund

# Generate per-repo JSON reports (in each repo or in CI)
guardlink report --format json -o guardlink-report.json

# Merge all reports into a unified dashboard
guardlink merge payment-svc.json auth-lib.json api-gateway.json \
  -o dashboard.html --json merged.json

# Week-over-week diff for security leads
guardlink merge *.json --diff-against last-week.json --json merged.json

注释通过标记前缀引用同级存储库-- @flows #request from #api-gateway.router to #payment-svc.refund --这些引用在合并过程中解析。 guardlink validate 将它们标记为本地外部引用，但它们是预期的，不会阻止CI。

有关自动化的每周仪表板，请参阅 CI设置指南.完整的工作空间文档： docs/WORKSPACE.md.

______________________________________________________________________

真实世界结果

我们测试了GuardLink+克劳德代码 漏洞代码js-express.js-app，一个故意易受攻击的Express.js应用程序，有37种记录在案的漏洞类型。

在6分钟内，无需人为干预：

• 6个管线文件中的143个注释
• 通过CWE映射识别出29种不同的威胁
• 66次未缓解的暴露记录，文件：行精度
• 检测到37个已知漏洞中的27个（召回率73%，部分匹配率81%）
• 架构：8个资产，3个数据流，带风险热图的美人鱼图
• 成本：Haiku代币约0.50美元

扫描仪会给你一份发现清单。GuardLink为您提供了一个威胁模型——资产、威胁、控制、数据流、信任边界以及它们之间的关系。每次暴露都可以追溯到一行代码。每个缓解措施都记录在其实施的控制措施旁边。而且因为它都在代码注释中，所以当代码更改时，它会更新。

______________________________________________________________________

库API

import { parseProject } from 'guardlink/parser';
import { generateReport } from 'guardlink/report';
import { diffModels } from 'guardlink/diff';
import { generateSarif } from 'guardlink/analyzer';
import type { ThreatModel } from 'guardlink';

const { model } = await parseProject({ root: '.', project: 'my-app' });

const markdown = generateReport(model);
const diff = diffModels(oldModel, newModel);
const sarif = generateSarif(model, '.');

______________________________________________________________________

规格

GuardLink是一个开放规范。注释语法、威胁模型模式和一致性级别在 GuardLink规范.

任何人都可以构建符合要求的解析器、分析器或集成。此CLI是参考实现。

此实现是 级别4 一致。

______________________________________________________________________

遗产

GuardLink基于由创建的注释语法 威胁规格 Fraser Scott（2015-2020）-第一个通过代码注释提出连续威胁建模的工具。核心动词(@mitigates, @exposes, @transfers, @accepts)源于这项工作。

我们通过严重性级别、外部引用（CWE/CAPEC/OWASP）、数据流和信任边界注释、数据分类、结构化JSON模式、SARIF导出、人工智能代理的MCP集成和CI/CD执行工具扩展了规范。ThreatSpec的想法是正确的。我们的贡献是让它在人工智能编写大部分代码的世界中发挥作用。

______________________________________________________________________

贡献

看 贡献.md.

许可证

麻省理工学院——见 许可证GuardLink规范在CC-BY-4.0下发布。

______________________________________________________________________

建造于 BugB技术.