尧图网站设计 尧图网站设计YAOTU DESIGN
ARTICLE DETAIL

资讯详情

深耕网站设计与一线实操的经验洞察。

capa rules 文档网站构建指南:基于 just + pagefind 的规则库静态站点生成

capa rules 文档网站构建指南:基于 just + pagefind 的规则库静态站点生成 capa rules 文档网站构建指南基于 just pagefind 的规则库静态站点生成【免费下载链接】capaThe FLARE teams open-source tool to identify capabilities in executable files.项目地址: https://gitcode.com/GitHub_Trending/ca/capacapa 是 FLARE 团队开源的恶意软件能力识别工具其 YAML 规则库规模庞大需要一个结构清晰、可全文检索的在线文档来承载。本指南围绕仓库中 web/rules/README.md 展开完整讲解 capa rules 文档网站的构建流程从依赖安装、just任务编排到三条 Python 脚本如何把 YAML 规则渲染为静态 HTML再到 Pagefind 全文检索与本地预览/部署。读完本文你将掌握该站点从零构建到发布的全过程并能基于源码理解每个构建环节的底层实现。项目定位与目录结构capa 仓库在web/rules/下维护了一个独立的静态文档站点用于以网页形式呈现全部 capa 规则规则本体位于仓库根目录的 rules/。该站点区别于主仓库的 web/explorer 交互式分析界面定位是面向规则开发者的规则浏览、检索与溯源入口。站点核心目录与文件如下web/rules/README.md站点说明文档也是本指南的依据web/rules/justfilejust任务配方定义构建、清理、预览等命令web/rules/requirements.txtPython 依赖清单web/rules/scripts/modified-dates.py扫描规则文件、按最近修改时间分类web/rules/scripts/build_rules.py为每条规则生成独立 HTML 页面web/rules/scripts/build_root.py生成站点首页规则卡片列表 搜索框web/rules/public/产物目录包含 Bootstrap 5.3.3、jQuery、Pagefind UI、Poppins 字体与站点 Logo 等静态资源。从代码注释看这些脚本的版权归属 Google LLC2024采用 Apache-2.0 许可与仓库主 LICENSE 一致。环境要求requirements在开始构建前需要准备三样东西just一个通用命令运行器用于执行justfile中定义的构建任务clean、build、serve等pagefind静态网站全文搜索引擎负责对生成后的public/目录建立索引提供站内搜索能力Python 依赖在web/rules/目录下执行pip install -r requirements安装。web/rules/requirements.txt 的完整内容只有三行但每一行都不可省略pyyaml6.0.2 pygments2.20.0 -e ../.. # capapyyamlYAML 解析用于读取规则文件pygments代码高亮用于把规则 YAML 渲染成带语法高亮的 HTML-e ../..以可编辑editable模式安装仓库根目录的 capa 主包。这是关键依赖——构建脚本会通过import capa.rules调用主项目中的规则解析器见下文源码分析因此必须先让 capa 包可被导入。构建流程总览justfile 任务编排web/rules/justfile 是整个构建流程的指挥中枢定义了 5 个可执行任务相互之间按依赖关系串联modified-dates: python scripts/modified-dates.py ../../rules/ ./file_modification_dates.txt build-rules: mkdir -p ./public/rules/ python scripts/build_rules.py ../../rules/ ./file_modification_dates.txt ./public/ build-root: python scripts/build_root.py ../../rules/ ./file_modification_dates.txt ./public/ index-website: build-rules build-root pagefind --site public build: modified-dates build-rules build-root index-website clean: rm -f file_modification_dates.txt rm -f public/index.html rm -rf public/*.html rm -rf public/pagefind serve: python -m http.server --b localhost --directory ./public逐条拆解各任务的职责任务职责输出modified-dates扫描../../rules/仓库根目录的 rules/下所有.yml规则用git log获取每条规则的最后修改时间按时间区间分类写入./file_modification_dates.txt中间产物已被 web/rules/.gitignore 忽略build-rules先创建./public/rules/目录再为每条规则渲染独立 HTML 页面public/rules/rule-name/index.html及重定向页build-root读取分类文件生成站点首页public/index.html规则卡片 搜索框public/index.htmlindex-website依赖build-rules和build-root随后调用pagefind --site public对全部产物建索引public/pagefind/索引文件build一键全流程modified-dates → build-rules → build-root → index-website完整静态站点clean删除file_modification_dates.txt、public/index.html、public/pagefind/及全部顶层 HTML恢复干净状态serve用 Python 内置 HTTP 服务器在 localhost 上预览站点本地服务值得注意的是index-website与build-root都声明了依赖项。just会在执行任务前自动先运行其声明的依赖任务因此手动执行just index-website时也会连带完成规则页与首页的构建。file_modification_dates.txt与public/下的生成内容index.html、pagefind/都在 web/rules/.gitignore 中被忽略说明它们属于构建期产物而非源码重新just build即可再生。第一步扫描规则修改时间modified-dates.pyweb/rules/scripts/modified-dates.py 负责回答一个问题每条规则最近一次被改动是什么时候脚本的核心逻辑用os.walk递归遍历规则目录跳过以.开头的隐藏目录只收集.yml文件对每个文件在其所在目录中执行git log -1 --pretty%ct filename取该文件最近一次提交的 Unix 时间戳按“最近一天 / 最近一周 / 最近一个月 / 最近三个月 / 最近一年 / 更早older”五个时间窗口对文件分类把分类结果按“ 分类名 每行文件路径 修改时间”的格式写入file_modification_dates.txt。该中间文件的格式被后续两个脚本共同消费build_rules.py 用它查询每条规则页面的“last edited”时间戳build_root.py 用它把首页规则卡片按“最近更新”分组展示。从源码看modified-dates.py依赖当前目录是一个 git 仓库需要git log可用这是该脚本的隐含前提若规则目录不在 git 版本控制下此步骤会失败。第二步渲染规则详情页build_rules.pyweb/rules/scripts/build_rules.py 是站点内容生成的核心每一条规则都会生成一个独立的、可直接被搜索引擎索引的静态页面。调用 capa 主包的规则解析器脚本通过import capa.rules复用主项目的规则解析能力rule capa.rules.Rule.from_yaml(rule_content, use_ruamelTrue)对应主包实现位于 capa/rules/init.py其中Rule.from_yaml负责把 YAML 文本解析为Rule对象。规则名称rule.name、命名空间rule.meta.get(namespace, )都来自解析结果。这印证了requirements.txt中-e ../..的必要性构建脚本直接依赖 capa 主包的解析器而不是自己重复实现 YAML 解析逻辑。页面内容与辅助链接每条规则页面包含YAML 源码高亮展示通过 Pygments 的YamlLexer对规则原文高亮HtmlFormatter使用xcode风格、noclassesTrue内联样式无需额外 CSS 类即可独立呈现命名空间面包屑页面顶部显示规则所属命名空间并链接回首页按该命名空间过滤的搜索../?qnamespace: xxx 两个实用外链入口“edit on GitHub”指向 capa-rules 仓库对应命名空间路径下的规则源文件“search on VirusTotal”构造behavior_signature:规则名查询并 URL 编码在 VirusTotal 上检索命中该行为签名的样本last edited 时间戳取自modified-dates阶段生成的时间映射。双路径 URL 设计canonical 与 redirect脚本为每条规则生成两个 HTML 文件这是页面 URL 设计的精妙之处canonical 路径public/rules/规则显示名/index.html。规则显示名来自rule.name中间允许包含空格例如rules/create file/index.html对应 URLrules/create%20file/重定向路径public/rules/规则文件名不含扩展名/index.html即rules/create-file/index.html。该页面仅含一行meta http-equivrefresh content0; url../规则显示名/。重定向路径的存在是为了让规则 ID文件名也能访问。由于站点通常托管在 GitHub Pages 这类静态服务器上无法配置服务端 HTTP 301因此选用meta refresh 前端跳转方案脚本注释明确说明了这一取舍。这样rules/create-file/会自动跳到rules/create file/两个 URL 都能访问同一条规则。第三步生成站点首页build_root.pyweb/rules/scripts/build_root.py 生成站点门户页面public/index.html核心功能是把全部规则以“最近更新卡片墙 全文搜索”的形式呈现。按更新时间分组的卡片墙首页读取file_modification_dates.txt按六个时间窗口最近一天/一周/一个月/三个月/一年/更早分节展示规则。每条规则渲染为一张卡片包含命名空间灰色小字规则名称黑色粗体链接到对应详情页./规则名/作者rule.meta.get(authors, [])多个作者用逗号连接。卡片使用 CSS Grid 四列布局末尾通过计算补齐空位(4 - num_cards % 4) % 4隐藏占位卡片保证网格整齐。命名空间配色脚本维护了一个 17 色预定义色板按命名空间首段如runtime、anti-analysis分配左侧竖条颜色色板用尽后则用random生成随机色并保证不与已用颜色重复。这让来自同一命名空间的规则在视觉上形成一致性分组。Pagefind 搜索集成首页在DOMContentLoaded时初始化PagefindUIconst search new PagefindUI({ element: #search, showSubResults: true, showEmptyFilters: false, excerptLength: 15, });并支持从 URL 查询参数?q...直接触发搜索——这正是规则详情页命名空间链接../?qnamespace: xxx 能“跳回首页并自动过滤”的原理。同时详情页的规则正文包裹在data-pagefind-body属性中Pagefind 会以此限定索引范围实现仅索引规则正文的精准全文检索。第四步全文索引pagefindindex-website任务在规则页与首页生成后执行pagefind --site publicPagefind 会扫描public/下的全部 HTML生成public/pagefind/索引目录该目录同样被 .gitignore 忽略。站点所需的 UI 资源pagefind-ui.js、pagefind-ui.css、pagefind-modular-ui.css已随仓库静态资源提交在 web/rules/public/css/ 与 web/rules/public/js/构建产物直接引用./pagefind/下的运行时文件。本地预览与部署构建完成后两种使用方式README 明确给出1. 本地预览执行just serve然后访问 http://127.0.0.1:8000/ 即可查看完整站点。其底层命令是python -m http.server --b localhost --directory ./public即以public/为根目录启动 Python 内置静态服务器--b localhost表示仅绑定回环地址仅本机可访问。2. 部署上线just build之后把./public目录整体上传到任意静态托管即可无需服务器端渲染。README 中的原话是“upload./publicsomewhere”。考虑到站点是纯静态产物HTML CSS JS Pagefind 索引它天然适合 GitHub Pages、CDN 或对象存储等任何静态托管环境。完整实操从零构建站点综合以上分析一次完整的构建与预览操作如下# 1. 安装 Python 依赖需在 web/rules 目录下 pip install -r requirements # 2. 安装 just 与 pagefind各自项目的官方安装方式 # 3. 一键构建等价于依次执行 # modified-dates - build-rules - build-root - index-website just build # 4. 本地预览 just serve # 浏览器访问 http://127.0.0.1:8000/ # 5. 需要重新构建时先清理产物 just clean构建完成后public/目录的产物结构大致如下public/ ├── index.html # 首页按更新时间分组的规则卡片 搜索框 ├── rules/ │ └── 规则名/index.html # 每条规则一个独立页面含高亮 YAML、外链、时间戳 ├── pagefind/ # pagefind 全文索引构建产物 ├── css/ # Bootstrap、Poppins、Pagefind UI、站点样式 ├── js/ # jQuery、Bootstrap bundle 等脚本 └── img/ # logo、favicon构建链路的依赖关系小结整个站点的数据流可以概括为一条清晰的流水线rules/ 下的 YAML 规则 │ modified-dates.pygit log 取修改时间 ▼ file_modification_dates.txt ──► build_rules.py逐条渲染详情页 重定向页 │ build_root.py生成首页卡片墙 搜索框 ▼ public/ 静态 HTML │ pagefind --site public ▼ public/pagefind/ 索引 ──► 本地 just serve 预览 / 上传托管部署理解这条链路后无论是新增规则自动出现在站点中还是定制首页样式、调整时间分类窗口都可以在 web/rules/scripts/ 的三个脚本与 web/rules/justfile 中直接定位修改点。例如想调整“最近更新”的分组粒度改 modified-dates.py 中categories列表的timedelta参数即可想改变规则页的外链集合则在 build_rules.py 的render_rule函数中维护链接模板。延伸阅读若希望深入理解站点背后的规则解析与渲染机制可以继续研读以下仓库内容capa/rules/init.pyRule.from_yaml/from_yaml_file的实现站点解析规则的底层引擎tests/test_rules.py规则解析与匹配的测试用例可验证规则语法rules/站点内容的来源——仓库内实际收录的 YAML 规则集web/rules/public/css/style.css首页与详情页共用的自定义样式。【免费下载链接】capaThe FLARE teams open-source tool to identify capabilities in executable files.项目地址: https://gitcode.com/GitHub_Trending/ca/capa创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表