【免费下载链接】Cybersecurity-ProjectsBuilding 70 Projects ranging from beginner to advanced so anyone can — learn from, build upon, use as a reference, or even copy directly. Gamified Cybersecurity learning 项目地址https://gitcode.com/gh_mirrors/cy/Cybersecurity-Projects点击查看免费下载本指南以开源仓库Cybersecurity-Projects中PROJECTS/intermediate/secrets-scanner项目代码名Portia的架构文档为核心逐层拆解其从命令行入口、配置解析、源码注入、规则匹配到并发流水线、HIBP 泄露核验与多格式报告的完整设计。读者将理解每个组件为何这样设计、请求如何在系统中流转以及关键词预过滤、Shannon 熵校验、五层误报过滤等关键技术决策背后的权衡。总体架构一个单向数据流的五段式管线Portia 的整体架构可以用一条「单向数据流」概括CLI 解析参数 → Source 产出文本块 → 并发 Pipeline 检测 → HIBP 可选核验 → Reporter 输出结果。源码层面的目录划分与之一一对应┌──────────────────────────────────────────────────────┐ │ CLI │ │ root.go, scan.go, git.go │ └───────────────────────┬──────────────────────────────┘ │ ┌─────────┴─────────┐ ▼ ▼ ┌──────────────┐ ┌──────────────┐ │ Directory │ │ Git │ │ Source │ │ Source │ │ directory.go │ │ git.go │ └──────┬───────┘ └──────┬───────┘ │ │ └─────────┬─────────┘ │ ▼ chan types.Chunk ┌─────────────────┐ │ Pipeline │ │ pipeline.go │ ├─────────────────┤ │ ┌───────────┐ │ │ │ Worker 1 │ │ │ │ detector │ │ │ └───────────┘ │ │ ┌───────────┐ │ │ │ Worker 2 │ │ │ │ detector │ │ │ └───────────┘ │ │ ┌───────────┐ │ │ │ Worker N │ │ │ │ detector │ │ │ └───────────┘ │ │ │ └────────┬────────┘ │ ▼ chan types.Finding ┌─────────────────┐ │ Collector │ │ dedup merge │ └────────┬────────┘ │ ┌────────┴────────┐ │ │ ▼ ▼ ┌──────────────┐ ┌──────────────┐ │ HIBP Check │ │ Reporter │ │ (optional) │ │ term/json/ │ │ client.go │ │ sarif │ └──────┬───────┘ └──────────────┘ │ ▲ └─────────────────┘这条管线有两大设计特点一是解耦各层只通过窄接口Source、chan types.Chunk、chan types.Finding、Reporter交互便于单独替换或测试二是逐级压缩从磁盘上任意文件到最终报告数据量在每个阶段都被显著收敛为全仓库扫描提供可控的资源消耗。所有共享数据结构Chunk、Finding、ScanResult、Rule统一定义在 pkg/types/types.go是整个系统各层之间的「契约」。组件逐层剖析CLI 层internal/cli/职责解析命令行参数并编排扫描流程。root.go用 Cobra。scan.go中的executeScan是scan与git两个命令共享的扫描驱动器internal/cli/scan.go它负责创建 Pipeline、可选地执行 HIBP 核验、并按格式选择 Reporter 写入 stdout。CLI 层通过cobra.OnInitialize(initConfig)在每条命令执行前完成配置合并——这保证了「CLI 标志优先于配置文件」的语义贯穿始终。入口链为cmd/portia/main.go→cli.Execute()→run()内部通过signal.NotifyContext捕获SIGINT/SIGTERM实现优雅退出→rootCmd.ExecuteContext(ctx)。配置加载器internal/config/职责加载并合并来自.portia.toml的配置。核心函数Load(path string) (*Config, error)internal/config/config.go在path为空时自动按以下顺序搜索配置文件.portia.toml当前目录.portia/config.toml~/.config/portia/config.toml全局通过os.UserHomeDir()定位命中第一个即加载不再检查后续路径。若三者都不存在则回退到pyproject.toml中的[tool.portia]表loadFromPyproject会先解析再校验该表是否真正含有效配置项避免空表干扰。Config结构体按 TOML 分为五个 section与 internal/config/config.go 一一对应Section字段说明[rules]disable/enable禁用/启用指定规则 ID当前applyRuleConfig实际消费disable[scan]max_file_size/excludes/depth/since最大文件字节数默认1048576、排除模式、Git 扫描深度、起始日期YYYY-MM-DD[output]format/verbose/no_color输出格式、详细模式、禁用颜色[hibp]enabled是否启用 HIBP 泄露核验[allowlist]paths/values/stopwords路径/值白名单正则与停用词DefaultTemplate()与PyprojectTemplate()为portia init和portia pyproject命令提供可直接落盘的起始配置模板。Source 接口与两种实现internal/source/目的从不同输入目录、Git 历史产出文本块。接口极其精简internal/source/source.gotype Source interface { Chunks(ctx context.Context, out chan- types.Chunk) error String() string }目录源directory.goNewDirectory(path, maxSize, excludes)构造的Directory通过filepath.WalkDir遍历文件系统并执行四道跳过逻辑internal/source/directory.go跳过噪声目录.git、node_modules、vendor、__pycache__、.venv、venv、.svn、.hg、.tox、.mypy_cache、.pytest_cache、.ruff_cache、.next、.nuxt、.terraform、.gradle、Pods、coverage、.nyc_output、.bundle、target、.eggs跳过二进制扩展名binaryExts表覆盖图片、字体、音视频、压缩包、可执行文件、ML 模型.onnx、.safetensors等在内的 100 扩展名internal/source/directory.go跳过超大文件info.Size() d.MaxSize默认上限 1MBdefaultMaxFileSize 1 20跳过用户排除模式isExcluded同时支持filepath.Match的通配匹配与子串包含匹配internal/source/directory.go。幸存文本文件用bufio.Scanner缓冲上限 512KB逐行读取每 50 行打包成一个types.Chunk携带FilePath与LineStart起始行号通过 select ctx 检查后发送到输出通道internal/source/directory.go。Git 源git.go使用 go-git v5 在进程内操作仓库不依赖外部git命令。Git结构体含RepoPath、Branch、Since、Depth、StagedOnly、MaxSize、Excludes字段两种扫描模式scanHistory沿目标分支默认 HEAD可通过--branch指定按提交时间逆序遍历 commit log对每个 commit 的 tree 提取文件内容并把 commit 的Hash、作者邮箱、提交时间写入Chunkinternal/source/git.go。--since格式2006-01-02与--depth在LogOptions与迭代计数中生效scanStaged读取 git index 条目仅扫描git status中 Staging 或 Worktree 有变更的文件未修改文件直接跳过internal/source/git.go。注意git.go的源层会额外调用f.IsBinary()做内容级二进制探测对目录源是一种互补。两者最终都经由splitIntoChunks切成 50 行的块空块会被剔除。规则注册表internal/rules/目的存储检测规则并提供基于关键字的快速查找。Registry内部是map[string]*types.Rule加disabled map[string]bool公开接口为Register(rule)、Get(id)、All()、Disable(ids...)、MatchKeywords(content)、Len()internal/rules/registry.go。Register对重复规则 ID 直接 panic——这保证了内置规则集的唯一性。内置规则由builtin.go中的builtinRules切片定义经RegisterBuiltins(reg)批量注入实测该切片含150 条ID:定义覆盖 AWSAccess Key ID / Secret Access Key / Session Token、GitHubfine-grainedgithub_pat_、classicghp_、OAuth、GitLab、GCP、Azure、Slack、Stripe、Twilio、SendGrid、Shopify、npm、PyPI、JWT、SSH 私钥、数据库连接串等internal/rules/builtin.go 可见开头样例。每条Rule的关键字段见 pkg/types/types.go字段作用Keywords预过滤用的关键字列表如AKIA、ghp_、sk_livePattern已编译的正则如\b(ghp_[a-zA-Z0-9]{36})\bSecretGroup捕获组索引用于从整段匹配中精准提取 secretEntropy可选的 Shannon 熵下限低于则丢弃SeverityCRITICAL/HIGH/MEDIUM/LOW此外注册表还持有两个编译期白名单GlobalPathAllowlist锁定文件go.mod/go.sum/各类 lockfile、node_modules/、vendor/、.git/、构建目录target|build|dist|out/、.min.js/.css、二进制扩展名等与GlobalValueAllowlistexample/test/dummy/placeholder前缀、xxxx、****、${...}、{{...}}、UPPER、null/nil/undefined、dGVzdA等 Base64 编码的示例值、PUT_YOUR_等占位前缀internal/rules/registry.go。检测引擎internal/engine/检测引擎由三部分构成是整个系统的核心。Detectordetector.goDetector.Detect(chunk)的处理顺序internal/engine/detector.go调用registry.MatchKeywords(chunk.Content)做关键字预过滤对每条命中规则逐行执行rule.Pattern.FindAllStringSubmatchIndex通过extractSecret按SecretGroup从捕获组提取 secret若规则带Entropy阈值用rules.DetectCharset判断字符集hex/base64/alphanumeric后调用ShannonEntropy计算低于阈值直接丢弃通过FilterFinding五层误报过滤后才构造成Finding入列。补充高熵兜底扫描。除规则检测外detectHighEntropy作为第二道防线专门捕获「没有被任何具体规则覆盖的高熵字符串」它只处理含赋值运算符、:、、:、||、,后跟字符串值的行按 Base64阈值 4.5与 hex阈值 3.5两个字符集切分出长度 ≥ 20 的高熵 token并以high-entropy-string规则 ID、MEDIUM严重度上报isAlreadyCaught会检查是否与既有发现重叠以避免重复报告internal/engine/detector.go。Filterfilter.goFilterFinding串联五层检查任一层命中即判定为误报internal/engine/filter.goIsPlaceholder对照GlobalValueAllowlist的占位/示例模式IsTemplated匹配 13 个模板引用正则覆盖${...}、{{...}}、os.getenv(、os.environ(、process.env.、System.getenv(、ENV[、env(、viper.Get、config.get(、config[、Value(${、% ENV[、{{ .Values.internal/engine/filter.goIsStopword先把 secret 转小写查内置停用词表再把 secret 按_-./切分成词元逐一比对。停用词表规模在 700 量级源码中约 700 个词条如password_hash、password_reset、sample、example、changeit等见 internal/engine/filter.go且支持规则的Allowlist.Stopwords追加词路径白名单文件路径对照GlobalPathAllowlist规则级白名单rule.Allowlist.Values与rule.Allowlist.Paths兜底。HasAssignmentOperator同时被高熵扫描复用是整个行上下文判断的基础。Pipelinepipeline.goNewPipeline(reg)按min(max(NumCPU, 2), 16)计算 worker 数internal/engine/pipeline.goRun(ctx, src)用 errgroup 编排 1 个 source goroutine N 个 worker goroutine 1 个 collector goroutineinternal/engine/pipeline.go。worker 从 chunks 通道取块、调用detector.Detect、把 findings 推入 findings 通道collector 用互斥锁追加到allFindings切片。结束后dedup以RuleID|FilePath|Secret|CommitSHA为键去重internal/engine/pipeline.go。HIBP 客户端internal/hibp/目的把检测到的 secret 与 Have I Been Pwned 泄露数据库比对。NewClient()组装了四层防护internal/hibp/client.goSHA-1 哈希 k-anonymity 前缀查询Check计算sha1Hash(secret)只向https://api.pwnedpasswords.com/range/发送前 5 位哈希前缀完整后缀在本地与响应中的SUFFIX:count行比对从而不把完整哈希交给第三方internal/hibp/client.goLRU 缓存10,000 条目避免同一 secret 重复查询熔断器连续 5 次失败触发60 秒冷却gobreaker配置ConsecutiveFailures 5、Timeout: 60s令牌桶限速rate.NewLimiter(rate.Every(200ms), 5)即每 200ms 一个请求、突发容量 5尊重 HIBP 公开 API 的速率约束。HTTP 层对 429 响应最多重试 3 次退避按attempt * 2s递增。在 CLI 层checkHIBP只对generic-password与generic-secret两条规则的发现执行核验其余规则标记HIBPSkippedinternal/cli/scan.go。报告器internal/reporter/Reporter接口只有Report(w io.Writer, result *types.ScanResult) error工厂New(format)按字符串分发internal/reporter/reporter.goTerminalterminal.go彩色表格输出CRITICAL 用红色、MEDIUM 用黄色secret 只显示首尾少量字符实现脱敏Git commit SHA 截断展示附 HIBP 泄露状态JSONjson.go结构化输出findings数组 summary对象secret 同样脱敏SARIFsarif.go输出 SARIF v2.1.0 合规 JSON含工具元数据、规则定义、带位置与属性的 results可被 GitHub Advanced Security 等 SARIF 消费者直接消费。数据流追踪portia scan ./myproject的七步之旅以目录扫描为例逐步骤还原一次完整扫描对应 internal/cli/scan.go 与 internal/engine/pipeline.go 的实际调用链1. CLI 解析参数 root.go:init() → cobra.OnInitialize(initConfig) scan.go:runScan() 收到 path./myproject 2. 配置加载 root.go:initConfig() → config.Load(cfgFile) CLI 标志与 TOML 配置合并 format 缺省为 terminalmaxSize 缺省为 1MB 3. 注册表装配 scan.go:runScan() → rules.NewRegistry() rules.RegisterBuiltins(reg) 150 条内置规则载入注册表 按配置禁用规则reg.Disable(cfg.Rules.Disable...) 4. 创建 Source scan.go:runScan() → source.NewDirectory(path, maxSize, excludes) 构造携带路径、最大文件大小、排除模式的 Directory 5. Pipeline 执行 scan.go:executeScan() → engine.NewPipeline(reg).Run(ctx, src) 5a. Source goroutine 启动 src.Chunks(ctx, chunks) WalkDir 遍历 ./myproject 跳过 .git / node_modules / vendor 与二进制扩展名 每个文件切成 50 行 chunk 发入 chunks 通道 5b. Worker goroutine按 NumCPU 取 2~16 个 各自从通道拉取 chunk执行 detector.Detect(chunk) - reg.MatchKeywords 关键字预过滤 - 对每条命中规则逐行跑 rule.Pattern 正则 - 从捕获组提取 secret - 有熵阈值的规则计算 Shannon 熵并比较 - FilterFinding 五层误报过滤IsPlaceholder → IsTemplated → IsStopword → 路径白名单 → 规则白名单 - 全部通过则构造 Finding 发入 findings 通道 5c. Collector goroutine 从 findings 通道拉取互斥锁追加到 allFindings 5d. errgroup.Wait 等待全部完成 按 ruleIDfilePathsecretcommitSHA 去重 6. HIBP 核验若启用 --hibp scan.go:checkHIBP(ctx, result) 逐条对 generic-password / generic-secret 调用 client.Check 回写 finding.HIBPStatus 与 finding.BreachCount 7. 报告输出 scan.go:executeScan() → reporter.New(format).Report(os.Stdout, result) Terminal按严重度着色的表格file:line 脱敏 secret JSON结构化输出到 stdout SARIFSARIF v2.1.0 JSON 到 stdout其中executeScan在整个过程中包裹了一个 spinner非 verbose 模式与time.Since计时result.Duration会写入最终ScanResultinternal/cli/scan.go。并发模型errgroup、有界 worker 与背压Pipeline 采用 Go 的 errgroup 结构化并发模式internal/engine/pipeline.go四个设计决策值得细究为什么 worker 有界正则匹配是 CPU 密集型任务无界并行只会加剧上下文切换开销收益递减。min(max(NumCPU, 2), 16)的公式保证单核机器也有 2 个 worker大服务器最多 16 个既满足最低吞吐又避免资源竞争。为什么选 errgroup两个收益(1) 任一 goroutine 返回错误时errgroup 会取消共享 context所有 goroutine 通过gctx.Err()检查干净退出不会悬挂(2)g.Wait()阻塞到全部完成提供唯一的错误聚合点CLI 层只需判断一次返回值。通道如何定容两个通道chunks 与 findingsCh都缓冲workers * 4个元素。这允许 source 在 worker 消费之前提前生产避免发送阻塞同时不会无限膨胀内存一旦 worker 变慢、缓冲填满source 会自然阻塞在out - chunk上形成天然的背压机制。detectWg的用意worker 共享独立的sync.WaitGroup而 collector 作为 errgroup 中的 goroutine其「关闭 findingsCh」的动作被放到独立 goroutine 中等待detectWg.Wait()之后执行internal/engine/pipeline.go。这防止了「collector 在所有 worker 产出完毕前就退出」的经典竞态保证 findings 完整收集。配置解析优先级三级覆盖配置按「默认值 → 配置文件 → CLI 标志」三级解析后者覆盖前者1. 硬编码默认值 Format: terminal MaxSize: 1MB (1 20) Workers: min(max(NumCPU, 2), 16) HIBP: 禁用 Verbose: false NoColor: false 2. 配置文件.portia.toml 依次搜索 .portia.toml当前目录 .portia/config.toml ~/.config/portia/config.toml 命中第一个即停全部缺失则回退 pyproject.toml 的 [tool.portia] 3. CLI 标志 --format / --verbose / --no-color / --exclude --max-size / --hibp / --config 永远优先于配置文件合并逻辑位于 internal/cli/root.go 的initConfig()其模式是先检查 CLI 标志是否被显式设置非零/非空只有未设置时才回退到配置文件的值。例如--max-size默认 0只有当其为 0 时才取cfg.Scan.MaxFileSize。--config标志则直接作为显式路径传给config.Load(cfgFile)跳过自动发现。规则匹配策略为速度而设计的四级漏斗正则匹配是昂贵操作因此检测链的目标是「尽可能不跑正则」。整个匹配过程是逐级收紧的漏斗Content chunk50 行代码 │ ▼ ┌───────────────────┐ │ Keyword Filter │ ← O(rules * keywords) strings.Contains │ 淘汰绝大多数规则 │ └────────┬──────────┘ │ 仅保留关键字命中的规则 ▼ ┌───────────────────┐ │ Line-by-Line │ ← O(lines * matched_rules) 正则 │ Regex Matching │ └────────┬──────────┘ │ 含捕获组的原始匹配 ▼ ┌───────────────────┐ │ Secret Extract │ ← 从捕获组提取 │ Entropy Check │ 低于阈值即丢弃 └────────┬──────────┘ │ 校验通过的候选 ▼ ┌───────────────────┐ │ Filter Chain │ ← IsPlaceholder → IsTemplated │ 五层误报过滤 │ → IsStopword → 白名单 └────────┬──────────┘ │ 真实发现 ▼ Finding第一级关键字预过滤是性能关键。如果一段 50 行的 HTML chunk 不包含password、secret、key、token、AKIA、ghp_、sk_live等任何关键字则零条规则命中、零个正则需要执行——实践中这能淘汰绝大多数 chunk。MatchKeywords的具体实现把 chunk 内容整体转小写后对每条规则的每个关键字做strings.Containsinternal/rules/registry.go属于典型的「以廉价字符串操作换昂贵正则操作」的取舍。架构权衡总结回顾整篇架构Portia 的设计选择可归纳为四组权衡并发 vs 简单errgroup 有界 worker 有界通道的组合在不引入 actor 框架的前提下获得并发吞吐、错误传播与背压三件事代价是代码里需要detectWg这类编排细节但全部集中在 internal/engine/pipeline.go 一个文件内召回 vs 误报150 条内置规则负责高置信度识别detectHighEntropy兜底低规则覆盖率的高熵字符串以 MEDIUM 严重度换取召回再靠五层过滤器占位符、模板引用、700 停用词、路径/值白名单压制误报速度 vs 完整度关键字预过滤牺牲了「规则在无关键字时也能命中」的完备性换取了大仓库扫描的可行时间大文件1MB与二进制文件被整体跳过进一步控制成本隐私 vs 功能HIBP 核验只上传 SHA-1 前 5 位前缀k-anonymity把泄露判断留在本地完成同时以缓存、熔断、限速三件套保护第三方 API 与自己。这些模式构成了一个高度可复用、可测试internal/engine/、internal/source/、internal/rules/、internal/hibp/、internal/reporter/下均有配套测试文件的 Go 秘密扫描参考实现。想深入源码的读者可从 pkg/types/types.go数据契约与 internal/engine/pipeline.go并发骨架两个入口继续研读也可以对照本系列文档 00-OVERVIEW.md、01-CONCEPTS.md、03-IMPLEMENTATION.md、04-CHALLENGES.md 获取完整脉络。赞分享【免费下载链接】Cybersecurity-ProjectsBuilding 70 Projects ranging from beginner to advanced so anyone can — learn from, build upon, use as a reference, or even copy directly. Gamified Cybersecurity learning 项目地址https://gitcode.com/gh_mirrors/cy/Cybersecurity-Projects点击查看免费下载相关推荐零日漏洞扫描器 lisdex 架构解析从源码树到披露报告的分阶段流水线设计零日漏洞扫描器 lisdex 架构解析从源码树到披露报告的分阶段流水线设计 导读 本文基于 zero day vulnerability scanner 项目终极Linux密码提取工具MimiPenguin从进程扫描到密码验证的完整解析终极Linux密码提取工具MimiPenguin从进程扫描到密码验证的完整解析 MimiPenguin是一款强大的Linux密码提取工具能够从当前Linuxtm-core listTasks 架构解析从 CLI 到存储层的端到端任务查询流水线设计tm core listTasks 架构解析从 CLI 到存储层的端到端任务查询流水线设计 claude task master 仓库中的 packages/AI Agent开发工具CLIMCP上一篇TrollStore技术实现iOS应用永久签名与权限管理指南下一篇Chatbox主题系统架构深度解析与技术实现创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考