denisfreitas999/lgpd-compliance-lsp

## 📖 关于本项目 **LGPD Compliance LSP** 是一个构建在 **Language Server Protocol (LSP)** 之上的静态分析服务器，用于在代码编辑器中——同样也在 **CI/CD** pipeline 中——实时检测违反 **Lei Geral de Proteção de Dados (LGPD)**（通用数据保护法）要求的行为。 该项目将 **Compliance as Code** 框架具象化：将 LGPD 的法律要求转化为**非功能性需求 (RNFs)**，并由此转化为可执行的**静态分析规则**。其结果是，该工具允许开发人员**在编写代码时**识别出不合规风险——例如日志中的个人数据泄露、使用不安全的协议或不受控制的不可逆数据删除——而不仅仅是在后续的审计中发现。 本仓库是塞尔希培联邦大学 (PROCC/UFS) 计算机科学研究生项目所辩护的一篇硕士论文的技术产物，在[研究背景](#-contexto-de-pesquisa)部分有详细描述。该软件还是一个**已在 INPI 提交注册申请的计算机程序**（参见 [INPI 注册](#-registro-no-inpi)），版权归塞尔希培联邦大学所有。 ### ✨ 主要功能 - 🔍 **实时检测 (shift-left security)** —— 诊断信息会在您输入代码时出现在 IDE 中，并具有 300ms 的 debouncing（防抖）延迟。 - 🧩 **11 条静态分析规则**，源自 LGPD 的 3 个 RNFs（RNF-07、RNF-08 和 RNF-12）。 - 🛠️ **上下文 Code Actions** —— 查看规则文档、忽略诊断（行或文件）以及自动修复（例如：`http://` → `https://`）。 - 🚦 **CI/CD pipeline 中的 Security gate** —— 相同的规则引擎可以在检测到不合规时中断构建。 - 🧱 **模块化与可扩展架构** —— 可以在不更改服务器核心的情况下添加新规则。 ## 🧠 工作原理 该服务器遵循 LSP 的标准生命周期：每当文档内容发生更改时，**客户端**（VS Code 扩展）和**服务器**（LGPD 规则引擎）就会通过 JSON-RPC 交换消息。 ``` flowchart LR A[Desenvolvedor edita código] -->|onDidChangeContent| B(LSP Core Engine\nserver.ts) B -->|debounce 300ms| C{validateDocument} C --> D[Motor de Regras\nserver/src/rules/*.ts] D --> E[keywords.ts\nDicionário de dados sensíveis] D --> F[Diagnósticos coletados] F --> G{Comentários de\nignore no arquivo?} G -->|lgpd-lsp-ignore-*| H[Filtra diagnósticos ignorados] G -->|Nenhum| I[publishDiagnostics] H --> I I --> J[IDE exibe alertas\nna aba Problems] J --> K[Code Actions:\nVer doc · Ignorar · Auto-fix] ``` 1. **触发** —— IDE 会在每次文档更改时通知服务器（`onDidChangeContent`）。 2. **编排** —— `validateDocument` 首先识别抑制注释（`lgpd-lsp-ignore-file`、`lgpd-lsp-ignore-next-line`），并构建要忽略的规则集。 3. **规则执行** —— `server/src/rules/` 中的每个模块都会使用 `keywords.ts` 作为个人/敏感数据的数据库，对文档内容应用其检测逻辑（主要是正则表达式和文本模式分析）。 4. **整合** —— 对所有规则返回的诊断进行聚合，并根据声明的异常情况进行过滤。 5. **发布** —— 最终列表通过 `textDocument/publishDiagnostics` 发送给客户端，在编辑器中以可视化方式标示出问题。 6. **辅助修复** —— 当开发者将光标悬停在诊断上时，会收到 Code Actions：打开规则文档（`docs/RNF-XX.md`）、抑制警告或应用自动修复（如果可用）。 ## 🔌 LSP 通信流程 选择 LSP 作为架构基础，解决了绑定在单一编辑器上的静态分析工具的经典问题：通过将分析逻辑（服务器）与界面（客户端）分离，理论上，任何兼容该协议的编辑器（VS Code、Neovim、IntelliJ 等）都可以重用相同的 LGPD 规则引擎，而无需重写检测逻辑。 ``` sequenceDiagram participant IDE as Cliente (VS Code Extension) participant LSP as Servidor LSP (server.ts) participant Rules as Motor de Regras (rules/*.ts) IDE->>LSP: initialize / initialized IDE->>LSP: textDocument/didOpen LSP->>Rules: validateDocument(conteúdo) Rules-->>LSP: Diagnostic[] LSP->>IDE: textDocument/publishDiagnostics IDE->>LSP: textDocument/didChange (debounce 300ms) LSP->>Rules: validateDocument(conteúdo atualizado) Rules-->>LSP: Diagnostic[] LSP->>IDE: textDocument/publishDiagnostics IDE->>LSP: textDocument/codeAction (cursor sobre diagnóstico) LSP-->>IDE: CodeAction[] (Ver doc / Ignorar / Auto-fix) IDE->>LSP: workspace/executeCommand (lgpd-lsp.openDoc) LSP-->>IDE: Abre docs/RNF-XX.md ``` 该协议避免了传统模型（每个编辑器进行一次静态分析集成）中典型的重复劳动，将检测智能集中在一个单一的服务器进程中，该进程通过标准化的消息契约与任何客户端进行通信。 ## 📂 项目结构 ``` 📦lgpd-compliance-lsp ┣ 📂client # Extensão cliente do VS Code (LSP Client) ┃ ┣ 📂src ┃ ┃ ┗ 📜extension.ts # Ponto de entrada da extensão / ativação do cliente LSP ┃ ┗ 📂out # Build transpilado da extensão ┃ ┣ 📂server # Núcleo do servidor LSP ┃ ┣ 📂src ┃ ┃ ┣ 📜server.ts # LSP Core Engine: ciclo de vida, debouncing, despacho de diagnósticos ┃ ┃ ┣ 📜analyze.ts # Orquestrador da função validateDocument ┃ ┃ ┣ 📜keywords.ts # Dicionário centralizado de dados pessoais/sensíveis ┃ ┃ ┗ 📂rules # Motor de Regras de Conformidade (uma regra por módulo) ┃ ┃ ┣ 📜index.ts # Agregador: exporta o array de todas as regras ativas ┃ ┃ ┣ 📜common.ts # Interface comum LgpdValidationRule e utilitários compartilhados ┃ ┃ ┣ 📜RNF-07-A.ts … 07-G.ts # Regras de prevenção contra cópia/exfiltração de dados (logs, rede, upload, e-mail, arquivos, serialização) ┃ ┃ ┣ 📜RNF-08.ts # Regra de proteção criptográfica em transmissão (protocolos inseguros) ┃ ┃ ┗ 📜RNF-12-A.ts … 12-C.ts # Regras de eliminação segura e irreversível de dados ┃ ┗ 📂out # Build transpilado do servidor ┃ ┣ 📂docs # Documentação just-in-time exibida via Code Action "Ver documentação" ┃ ┣ 📜RNF-07-A.md … RNF-07-G.md # Fundamentação legal, diretrizes e exemplos por regra ┃ ┣ 📜RNF-08.md ┃ ┗ 📜RNF-12-A.md … RNF-12-C.md ┃ ┣ 📜estrutura.svg # Diagrama de arquitetura do projeto ┣ 📜package.json # Workspace raiz (scripts de build/watch client + server) ┗ 📜tsconfig.json ``` ## ⚙️ 安装与使用 ### 前置条件 - [Node.js](https://nodejs.org/) ≥ 18 - [Visual Studio Code](https://code.visualstudio.com/) ### 构建 ``` # Clone o repositório git clone https://github.com/denisfreitas999/lgpd-compliance-lsp.git cd lgpd-compliance-lsp # 安装 client 和 server 的依赖 npm install cd client && npm install && cd .. cd server && npm install && cd .. # 编译这两个模块 npm run compile ``` ### 在 VS Code 中运行 1. 在 VS Code 中打开本仓库。 2. 按 `F5`（或使用 `.vscode/launch.json` 中的配置）启动一个加载了 LSP 客户端的 **Extension Development Host** 实例。 3. 打开一个包含例如 `console.log(cpf)` 的 `.ts`/`.js` 文件 —— 编辑器中应该会出现 RNF-07-A 的诊断信息并带有下划线提示。 4. 将光标置于诊断处，使用 `Ctrl+.`（Quick Fix）访问可用的 Code Actions（查看文档、忽略、自动修复）。 ### 在 CI/CD 中作为 gate 使用 相同的规则引擎可以在 IDE 之外作为 pipeline 的一个步骤被调用，当检测到不合规时返回一个错误退出代码——在交付之前中断构建。有关在实验验证中实现的参考场景，请参阅论文（6.2 节）中的 pipeline 配置示例。 ## 🧩 扩展框架 该架构的设计旨在确保在添加新规则、语言或法规时 LSP 引擎保持稳定。要实现一条新规则： 1. **在 `server/src/rules/` 中创建规则模块**，实现 `LgpdValidationRule` 接口（定义于 `common.ts`）。该函数必须接收文档内容，并在发现不合规时返回一个 `Diagnostic` 对象列表。 // server/src/rules/RNF-XX.ts import { LgpdValidationRule } from "./common"; export const RNF_XX: LgpdValidationRule = { id: "RNF-XX", validate(document) { // 检测逻辑（regex / 文本模式分析） return diagnostics; }, }; 2. **注册规则**，将其添加到 `server/src/rules/index.ts` 导出的数组中 —— 无需修改服务器核心（`server.ts`）。 3. 如果适用，**将词汇表添加**到 `keywords.ts` 中的集中字典里，以便多个规则可以重用相同的危险术语。 4. **记录规则**，创建 `docs/RNF-XX.md`，包含法律依据、实施指南和示例 —— 开发者可通过 Code Action “查看文档”查看此文件。 5. *（可选）* **实现自动修复**，注册一个自动修复的 Code Action，遵循 RNF-08（`http://` → `https://`）使用的模式。 ## 🏛️ INPI 注册 本仓库中实现的软件已作为**计算机程序**向隶属于巴西经济部的**国家工业产权局 (INPI)** 提交注册申请。 | 字段 | 信息 | |---|---| | **申请号** | BR 51 2026 004117 1 | | **标题** | LGPD Compliance LSP: Servidor de Análise Estática para Conformidade Contínua com a LGPD | | **申请日期** | 02/06/2026 | | **持有者** | 塞尔希培联邦大学 | | **作者** | Adicinéia Aparecida de Oliveira, Denisson Santos Alves de Freitas, Edward David Moreno Ordonez | | **语言** | JavaScript / 其他 (TypeScript) | | **程序类型** | DS-01, DS-06, GI-06, LG-02, PD-01 | 本仓库分发的 **CC BY-NC-ND 4.0** 许可证（参见[许可证](#-licença)）与 INPI 注册所赋予的保护是相容且不替代的；两者作为独立的保护层共存于同一软件中。 ## 🔬 研究背景 此 LSP 服务器是为以下硕士论文制作的核心技术产物： ### 三阶段方法论 | 阶段 | 描述 | |---|---| | **1. 需求提取** | 混合提取 —— LLMs 辅助初步提取，随后由专家进行人工筛选 —— 最终形成一个经验证的、源自 LGPD 的 **17 项非功能性需求 (RNFs)** 目录。 | | **2. 产物开发** | 将选定的 RNFs（07、08、12）转化为 11 条原子化的**静态分析规则**，并在此 LSP 服务器中采用模块化的 TypeScript 架构实现。 | | **3. 实验验证** | 在两种场景下进行概念验证评估：IDE 中的实时检测 (*shift-left security*) 以及作为 CI/CD pipeline 中的 *security gate* —— 在测试场景中**检测出了 100% 的故意违规行为**。 | ### 研究证实的假设 - **H1** —— 通过 LLMs + 人工筛选来系统地提取 LGPD 需求，是一种将法律义务结构化为可计算格式的有效方法。 - **H2** —— 将需求转化为集成到 LSP 服务器中的静态分析规则在技术上是可行的。 - **H3** —— 将 LSP 服务器集成到 DevSecOps pipeline 中，能够实现对不合规情况的早期检测和持续验证。 ### 相关科学出版物 - FREITAS, D. S. A.; OLIVEIRA, A. A.; MORENO, E. D.; SILVA, G. J. F. **DevSecOps Practices for GDPR, HIPAA or LGPD Compliance in Software Development: A Systematic Review.** 载于：*Anais do XXI Simpósio Brasileiro de Sistemas de Informação (SBSI 2025)*, Recife/PE, p. 145–153, 2025. DOI: [10.5753/sbsi.2025.246400](https://doi.org/10.5753/sbsi.2025.246400) - FREITAS, D. S. A. et al. **A Systematic Review of DevSecOps Practices for Regulatory Compliance: A Sociotechnical Perspective.** 提交给《*Computers & Security*》期刊的文章。 DOI: [10.5753/sbsi.2025.246400](https://dx.doi.org/10.2139/ssrn.5624228) - 第三篇文章正在准备中，整合了论文的全部贡献（概念框架、LSP 服务器架构和实验验证结果），准备提交给《*Software: Practice and Experience*》杂志。 ### 研究路线图（未来的工作） 在论文中讨论的演进方向中，值得注意的有：基于 **AST** 的语义分析（取代当前的词法分析）、扩大目录中其余 RNFs 的覆盖范围、支持生态系统中其他语言（Python、Java、C#）以及动态丰富敏感数据字典。 ## 📜 许可证 在 **Creative Commons Attribution-NonCommercial-NoDerivatives 4.0 International License (CC BY-NC-ND 4.0)** 下分发。 [](https://creativecommons.org/licenses/by-nc-nd/4.0/) 查看 [LICENSE](./LICENSE) 文件了解详情。

标签：DevSecOps, LGPD, LSP, MITM代理, 上游代理, 云安全监控, 安全专业人员, 网络安全, 自动化攻击, 隐私保护, 静态分析