nprasann/legacy-accessibility-static-crawler

# 遗留辅助功能静态爬虫 [](https://github.com/nprasann/legacy-accessibility-static-crawler/actions/workflows/ci.yml) [](https://github.com/nprasann/legacy-accessibility-static-crawler/releases) [](LICENSE) 面向生产环境的 .NET 8 / C# 静态无障碍评估爬虫，适用于现代和传统网站，包括针对可能需要 Microsoft Edge IE 模式的系统的辅助工作流。 核心系统无需 LLM、OpenAI、Azure OpenAI、Foundry 或任何云 AI 服务即可工作。未来可选的 LLM 支持仅通过一个已禁用的 `ILlmReviewService` 接口表示。 有关为非技术用户编写的分步说明，包括身份验证爬取和 Azure DevOps CSV 导出，请参阅 [docs/non-technical-user-guide.md](docs/non-technical-user-guide.md)。有关基于浏览器的 UI，请参阅 [docs/ui-mode.md](docs/ui-mode.md)。有关必需下载项、浏览器驱动程序和可移植发布包，请参阅 [docs/dependencies-and-packaging.md](docs/dependencies-and-packaging.md)。有关发布工程，请参阅 [docs/RELEASE.md](docs/RELEASE.md)。有关每个配置键，请参阅 [docs/configuration-reference.md](docs/configuration-reference.md)。 ## 功能 - 使用 Selenium 爬取已授权的网站。 - 支持 `modern-edge`、`chrome` 和 `edge-ie-mode-assisted` 模式。 - 捕获 HTML、截图、DOM 派生证据、标题、链接、按钮、表单、标签、图像、表格、iframe、ARIA 属性、可聚焦元素和传统风险。 - 针对内置规则包运行确定性静态检查。 - 可从提供的 PDF 中提取指导性覆盖层。 - 生成 JSON、HTML、Markdown、CSV、执行摘要和 Azure DevOps 待办项 CSV 报告。 - 导入手动发现，用于 IE 模式和辅助技术验证。 ## 本工具不做什么 此工具不： - 认证 ADA 合规性。 - 认证 WCAG 合规性。 - 认证 Section 508 合规性。 - 替代手动无障碍评审。 - 保证合规性。 - 需要 AI。 - 将敏感页面内容上传到云服务。 - 存储用户名或密码。 - 绕过身份验证或授权控制。 自动化测试不能替代手动无障碍测试。仍然需要屏幕阅读器、键盘、用户流和辅助技术测试。 ## 官方参考 - [ADA Title II 网络和移动应用无障碍规则](https://www.ada.gov/resources/2024-03-08-web-rule/) - [WCAG 2.1](https://www.w3.org/TR/WCAG21/) - [WCAG 2.2](https://www.w3.org/TR/WCAG22/) - [Section 508 测试资源](https://www.section508.gov/test/) - [ICT 测试基线](https://ictbaseline.access-board.gov/) ## 架构 ``` flowchart LR CLI["CLI Host"] --> Core["Core Rules and Static Engine"] API["ASP.NET Core API"] --> Core Core --> Infra["Infrastructure: Selenium, PDF, HTML, CSV"] Core --> Reporting["Reporting: HTML, Markdown, JSON, CSV, ADO"] Infra --> Browser["Edge / Chrome / IE-mode-assisted"] Infra --> PDF["User PDF Overlay"] Reporting --> Reports["Portable Reports"] ``` ## 版本锁定 项目版本：`Directory.Build.props` 和 `VERSION.txt` 中的 `1.0.0`。 运行时和主要包锁定： | 组件 | 版本 | | --- | --- | | .NET 目标框架 | `net8.0` | | Selenium.WebDriver | `4.27.0` | | Selenium.WebDriver.ChromeDriver | `131.0.6778.20400` | | Selenium.WebDriver.MSEdgeDriver | `147.0.3912.98` | | UglyToad.PdfPig | `1.7.0-custom-5` | | HtmlAgilityPack | `1.11.71` | | AngleSharp | `1.1.2` | | CsvHelper | `33.0.1` | | Scriban | `7.2.0` | | Swashbuckle.AspNetCore | `6.9.0` | | xUnit | `2.9.3` | 仓库关键词：`accessibility`、`wcag`、`ada-title-ii`、`section-508`、`selenium`、`dotnet-8`、`csharp`、`ie-mode`、`static-analysis`、`azure-devops`。 ## 下载发布版 从 [GitHub Releases](https://github.com/nprasann/legacy-accessibility-static-crawler/releases) 下载打包的发布版。 Windows: ``` Expand-Archive .\legacy-accessibility-static-crawler-1.0.0-win-x64.zip -DestinationPath .\legacy-accessibility-static-crawler cd .\legacy-accessibility-static-crawler .\legacy-a11y-crawler.exe --help .\legacy-a11y-crawler.exe version ``` Linux: ``` mkdir legacy-accessibility-static-crawler tar -xzf legacy-accessibility-static-crawler-1.0.0-linux-x64.tar.gz -C legacy-accessibility-static-crawler cd legacy-accessibility-static-crawler chmod +x ./legacy-a11y-crawler ./legacy-a11y-crawler --help ./legacy-a11y-crawler version ``` macOS Apple Silicon: ``` mkdir legacy-accessibility-static-crawler tar -xzf legacy-accessibility-static-crawler-1.0.0-osx-arm64.tar.gz -C legacy-accessibility-static-crawler cd legacy-accessibility-static-crawler chmod +x ./legacy-a11y-crawler ./legacy-a11y-crawler --help ./legacy-a11y-crawler version ``` 同时从发布版下载 `SHA256SUMS.txt` 并在内部分发前验证包哈希值。此工具是无障碍评估助手；它不认证 ADA、WCAG 或 Section 508 合规性。 ## 规则来源 内置规则包位于 `src/LegacyAccessibilityCrawler.Core/RulePacks/`： - `wcag-2.1-aa-static-rules.json` - `section-508-static-rules.json` - `wcag-2.2-static-rules.json` - `rule-mapping.json` PDF 派生的规则是指导性覆盖层。它们丰富了严重性、映射、描述和补救文本，但不替代内置的确定性检查。 ## CLI 示例 提取 PDF 指导： ``` dotnet run --project src/LegacyAccessibilityCrawler.Cli -- extract-rules \ --rules-pdf ./samples/sample-rules.pdf \ --output ./reports/rules ``` Modern Edge 爬取： ``` dotnet run --project src/LegacyAccessibilityCrawler.Cli -- crawl \ --url https://example.gov \ --browser modern-edge \ --max-pages 25 \ --depth 2 \ --standard wcag21aa \ --output ./reports/example ``` Chrome 爬取： ``` dotnet run --project src/LegacyAccessibilityCrawler.Cli -- crawl \ --url https://example.gov \ --browser chrome \ --max-pages 25 \ --depth 2 \ --output ./reports/example-chrome ``` Edge IE 模式辅助爬取： ``` dotnet run --project src/LegacyAccessibilityCrawler.Cli -- crawl \ --url https://legacy.example.gov \ --browser edge-ie-mode-assisted \ --manual-session true \ --max-pages 10 \ --depth 1 \ --rules-pdf ./samples/sample-rules.pdf \ --output ./reports/legacy-ie ``` 从现有扫描结果生成报告： ``` dotnet run --project src/LegacyAccessibilityCrawler.Cli -- report \ --scan-results ./reports/example/scan-results.json \ --output ./reports/example/final ``` 版本： ``` dotnet run --project src/LegacyAccessibilityCrawler.Cli -- version ``` ## API 运行启用 Swagger 的 API： ``` dotnet run --project src/LegacyAccessibilityCrawler.Api ``` 端点： - `POST /api/crawl/start` - `POST /api/rules/extract` - `POST /api/findings/import` - `POST /api/report/generate` - `GET /api/jobs/{id}` - `GET /api/reports/{id}` - `GET /api/rulepacks` - `GET /api/rulepacks/{id}` - `GET /api/version` API 路由需要 `x-api-key` 请求头。在进程环境中使用 `ApiSecurity__ApiKeys__0` 或 `LEGACY_A11Y_API_KEY` 配置密钥；没有提交默认 API 密钥。API 爬取也受到配置中 `Crawler:AllowedDomains` 的限制，该设置应仅包含您有权测试的系统。 ## 浏览器 UI 运行 API 并打开： ``` http://localhost:5000/ui/ ``` 该 UI 提供一个爬取表单，包含常用选项的下拉菜单和文本框，包括浏览器模式、规则包、最大页面数、爬取深度、可选的 PDF 规则路径、手动登录模式和无头执行。仪表盘列出生成的报告，并直接链接到 HTML 报告、发现项 CSV、JSON 报告、执行摘要和 Azure DevOps `ado-items.csv`。 UI 包含一个 API 密钥字段，因为本地 API 受到保护。在开始爬取前，请在 `appsettings.json` 中配置授权的目标域和 API 密钥。 ## IE 模式 IE 模式系统有所不同，因为传统控件、ActiveX、旧文档模式、框架和浏览器兼容层可能不会暴露完整的自动化证据。在 `edge-ie-mode-assisted` 模式下，该工具支持手动登录/会话续接，并且当 DOM 捕获有限或检测到传统风险时，会自动添加一个传统手动审查发现项。 ## 手动发现项 可以使用 `samples/sample-manual-findings.csv` 中的示例形状从 CSV 导入手动发现项。将其用于屏幕阅读器结果、键盘发现项、IE 模式验证以及静态扫描无法证明的工作流问题。 ## 可下载的可执行文件 / 可移植发布版 初始分发基于 ZIP 格式。后续可能会提供 MSI 安装程序，但可移植 ZIP 更容易获得批准并在测试工作站上运行。 1. 从 GitHub Releases 下载适用于您平台的 ZIP 文件。 2. 在已批准的测试工作站上解压文件夹。 3. 查看 `appsettings.example.json`。 4. 运行可执行文件。 用户在使用自包含发布 ZIP 时无需 .NET SDK。他们仍然需要安装 Chrome 或 Edge。WebDriver 二进制文件在支持的情况下通过 Selenium 驱动程序包包含，但浏览器版本和驱动程序版本必须保持兼容。 Windows 示例： ``` legacy-a11y-crawler.exe --help legacy-a11y-crawler.exe crawl ^ --url https://example.gov ^ --browser modern-edge ^ --max-pages 25 ^ --depth 2 ^ --standard wcag21aa ^ --output reports/example ``` ## 发布 CLI 自包含发布示例： ``` ./scripts/publish-win-x64.ps1 -Version 1.0.0 ``` ``` ./scripts/publish-linux-x64.sh 1.0.0 ./scripts/publish-osx-arm64.sh 1.0.0 ``` 发布 ZIP 包含可执行文件、`appsettings.example.json`、README、文档、示例、LICENSE、VERSION.txt 和 CHANGELOG.md。 发布 ZIP 不包含报告、截图、原始 HTML 捕获、`.env`、凭据、Cookie 或浏览器配置文件数据。 有关详细的依赖项和打包矩阵，请参阅 [docs/dependencies-and-packaging.md](docs/dependencies-and-packaging.md)。 ## 敏感数据 报告、截图和原始 HTML 可能包含敏感信息。请使用同域爬取、查询字符串脱敏、已批准的输出位置以及不存储凭据的手动登录。不要提交生成的报告或捕获内容。 ## 测试 ``` dotnet test legacy-accessibility-static-crawler.sln ``` 测试覆盖包括规则加载、WCAG/Section 508 映射、静态检查、报告生成、ADO 导出、IE 模式免责声明行为、无 AI 模式和手动发现项导入。

标签：ADA Title II, ARIA属性检查, Azure DevOps集成, DOM证据提取, ESC漏洞, HTML内容分析, IE模式辅助, .NET 8, PDF规则叠加, Section 508, Selenium自动化, WCAG 2.1 AA, Web可访问性, 企业级工具, 可访问性测试, 可访问性评估, 截图捕获, 焦点元素分析, 离线优先, 证据收集, 辅助审查工作流, 遗留网站支持, 静态爬虫