cspkit
MoonBit-native Content-Security-Policy parser, auditor, and diff toolkit.
csp
content-security-policy
security
policy-audit
web
moon add ZYK-ai-nb/cspkit@0.1.0
Download zipAuthor
Version
0.1.0
License
Apache-2.0
Last updated
4 hours ago
Downloads
3
README#CSPKit
CSPKit 是一个纯 MoonBit 实现的 Content-Security-Policy 解析、审计与差异分析工具库。它面向 MoonBit WebAssembly 应用、静态站点生成器、安全检查工具、API 网关和教学项目，提供可复用的 CSP 策略处理能力。
#选题独特性
在确定选题前，已检查 Mooncakes 模块列表中的 csp、content-security-policy、permissions-policy、feature-policy、security.txt 等关键词。其中 csp 与 content-security-policy 均为 0 命中。CSPKit 不做通用 HTTP 框架，也不做泛泛的字符串封装，而是聚焦 CSP 这一安全策略文本的解析、风险审计、fallback 计算和策略 diff。
#解决的问题
CSP 能限制脚本、样式、图片、frame 等资源来源，但实际策略经常包含 *、'unsafe-inline'、'unsafe-eval'、缺失 default-src、重复指令、'none' 与其他源混用等问题。CSPKit 把策略字符串解析成结构化数据，并输出可测试、可机器读取的审计结果，帮助 MoonBit 项目在发布前检查安全策略。
#适用场景
- MoonBit 静态站点或文档工具生成 CSP 时做发布前检查。
- WebAssembly 网关或边缘服务需要审计响应头。
- API mock、CI 工具、安全教学项目需要可复现的 CSP 解析示例。
- 包作者需要不依赖外部运行时的安全策略分析基础库。
#安装
Mooncakes 包名：
ZYK-ai-nb/cspkit在 MoonBit 项目中添加依赖：
moon add ZYK-ai-nb/cspkit在 moon.pkg 中导入：
import {
"ZYK-ai-nb/cspkit" @cspkit
}#最小使用示例
let policy = @cspkit.parse_policy(
"default-src 'self'; script-src 'self' 'unsafe-inline'",
).unwrap()
let findings = policy.audit()
println(findings.length())
println(policy.blocking_findings().length())#本地运行
moon check
moon build
moon test
moon run cmd/main示例输出：
directives=3
blocking=1
added=2
changed=1
header=default-src 'self'; script-src 'self' 'nonce-demo'; object-src 'none'; base-uri 'self'; frame-ancestors 'none'
score=100 grade=A penalty=0 bonus=13
templates=23 valid=23 clean=21 risky=2#核心功能
- parse_policy：解析 CSP 字符串为 Policy。
- Policy::directive / directives_named / contains：查询指令。
- Policy::effective_sources：计算 fetch directive 的 default-src fallback。
- Policy::audit：输出结构化风险 Finding。
- Policy::blocking_findings：筛选高风险问题。
- diff_policy：比较两个策略的新增、删除和变更指令。
- Policy::to_header：输出规范化策略字符串。
- classify_source_expression：识别 source expression 的类型、信任等级、scheme、host、port 和 path。
- directive_spec / known_directive_specs：提供 CSP 指令目录、分类和 fallback 元数据。
- Policy::score：输出策略评分、等级、扣分项和加分项。
- Policy::hardening_recommendations：生成可机器读取的加固建议。
- Policy::audit_text_report / audit_markdown_report / audit_json_report：生成文本、Markdown 和可转义的 JSON 审计报告。
- all_policy_templates：提供静态站点、SPA、WASM、管理后台、支付页、上传页等策略模板。
- audit_rule_catalog_report：提供审计规则目录和修复说明。
#支持范围
- CSP 指令按分号拆分，指令名 ASCII 小写规范化。
- source expression 按 ASCII 空白拆分，保留原始大小写。
- 识别 'self'、'none'、nonce、hash、scheme、host、wildcard、data:、blob: 等 source expression。
- 检查重复指令、缺失基线指令、通配符、HTTP 明文源、data: 风险源、'unsafe-inline'、'unsafe-eval'、'none' 混用。
- 对 fetch directives 提供 default-src fallback。
- 比较两份策略的 added、removed、changed。
- 按 Finding、source、directive coverage 计算策略分数。
- 输出文本、Markdown 和 JSON 风格报告。
- 提供 20 个以上可解析策略模板和规则目录。
#工程规模
当前 MoonBit 源码非空行数为 4390 行，其中去掉 /// 和 // 注释后的非注释代码为 4048 行。核心代码覆盖解析、审计、source 分类、指令目录、评分、报告、模板和规则目录，不使用空函数或无意义代码堆叠。
#暂不支持范围
- 不解析 HTML meta 标签或网络响应。
- 不实现浏览器完整 CSP 执行引擎。
- 不校验 nonce/hash 的真实加密摘要。
- 不处理 Report-To JSON、HTTP 日期或远程上报。
- 不包含浏览器兼容性数据库。
#测试与验收命令
moon fmt --check
moon info
moon check
moon check --deny-warn
moon build
moon test
moon test --deny-warn
moon run cmd/main
moon login
moon publish --dry-run#验收材料索引
#Mooncakes
- 包名：ZYK-ai-nb/cspkit
- 当前版本：0.1.0
- 仓库地址：https://github.com/ZYK-ai-nb/mooncake-auditor-public.git
- 发布流程：moon login 后执行 moon publish --dry-run，确认通过后执行 moon publish。
- moon.mod 只表示发布元数据已准备好；GitHub 公开同步和 mooncakes.io 发布状态应以对应远端页面为准。
#维护边界
CSPKit 的长期边界是 CSP 策略文本解析、审计、fallback 计算和策略 diff。项目不会扩展成通用 HTTP 框架、浏览器执行引擎或网络扫描器，以保持包体小、测试明确、后续维护成本可控。
#开源许可证与第三方说明
本项目采用 Apache-2.0 许可证。核心代码为 MoonBit 原生实现，不移植第三方源码，不包含图片、音频、字体或来源不明测试数据。
#贡献与安全
- 贡献流程见 CONTRIBUTING.md。
- 安全问题处理方式见 SECURITY.md。
#AuditRuleCategory
Catalog category for a CSPKit audit rule.
#AuditRuleSpec
pub(all) struct AuditRuleSpec {
code : String
category : AuditRuleCategory
severity : Severity
directive : String?
trigger : String
remediation : String
rationale : String
} derive(Eq, Debug)Static metadata for audit rules and recommendation mapping.
#Directive
#Directive::cryptographic_sources
#Directive::dangerous_sources
#Directive::has_cryptographic_source
#Directive::has_source_kind
#Directive::network_sources
#Directive::source_expressions
#DirectiveCategory
CSP directive families used by the catalog and reports.
#DirectiveCategory::is_security_core
#DirectiveChange
#DirectiveCoverage
Coverage for baseline and optional hardening directives.
#DirectiveCoverage::is_complete
#DirectiveSpec
pub(all) struct DirectiveSpec {
name : String
category : DirectiveCategory
fallback : String?
repeatable : Bool
level : String
description : String
} derive(Eq, Debug)Metadata for a known CSP directive.
#DirectiveSpec::is_experimental
#Finding
#HardeningRecommendation
pub(all) struct HardeningRecommendation {
code : String
priority : RecommendationPriority
directive : String?
summary : String
detail : String
} derive(Eq, Debug)Machine-readable hardening suggestion.
#HardeningRecommendation::detail_line
#HardeningRecommendation::json_line
#HardeningRecommendation::markdown_line
#HardeningRecommendation::summary_line
#ParseError
#Policy
#Policy::cryptographic_sources
#Policy::dangerous_sources
#Policy::deprecated_directives
#Policy::directive_catalog_summary
#Policy::directives_in_category
#Policy::directives_named
#Policy::effective_sources
#Policy::experimental_directives
#Policy::finding_remediation_report
#Policy::hardening_recommendations
#Policy::has_source_kind
#Policy::navigation_directives
#Policy::reporting_directives
#Policy::source_kind_count
#PolicyDiff
#PolicyGrade
Human-facing grade for the policy score.
#PolicyScore
pub(all) struct PolicyScore {
raw_score : Int
final_score : Int
penalty : Int
bonus : Int
grade : PolicyGrade
findings : SeverityCounts
directives : DirectiveCoverage
sources : SourceCounts
} derive(Eq, Debug)Full policy score model.
#PolicyTemplate
Named policy template for examples and quick starts.
#PolicyTemplate::audit_text_report
#PolicyTemplate::parse
#RecommendationPriority
Priority for a hardening recommendation.
#RecommendationPriority::name
#RecommendationPriority::weight
#ReportFlavor
Output flavor for audit reports.
#Severity
#SeverityCounts
Aggregated counts by finding severity.
#SourceCounts
Aggregated counts for classified CSP source expressions.
#SourceCounts::has_severe_source_risk
#SourceExpression
pub(all) struct SourceExpression {
raw : String
normalized : String
kind : SourceExpressionKind
trust : SourceTrust
scheme : String?
host : String?
port : String?
path : String?
description : String
} derive(Eq, Debug)Structured information derived from a raw CSP source expression.
#SourceExpression::allows_any_origin
#SourceExpression::allows_data_like_url
#SourceExpression::is_cryptographic
#SourceExpression::is_dangerous
#SourceExpression::is_host_with_path
#SourceExpression::is_local_like
#SourceExpression::is_network_source
#SourceExpression::is_wildcard_host
#SourceExpression::uses_plain_http
#SourceExpressionKind
pub(all) enum SourceExpressionKind {
SourceEmpty
SourceNone
SourceSelf
SourceUnsafeInline
SourceUnsafeEval
SourceWasmUnsafeEval
SourceStrictDynamic
SourceUnsafeHashes
SourceReportSample
SourceNonce
SourceSha256
SourceSha384
SourceSha512
SourceScheme
SourceHost
SourceWildcard
SourceData
SourceBlob
SourceFilesystem
SourceMediastream
SourceHttpsScheme
SourceHttpScheme
SourceUpgradeKeyword
SourceUnknownKeyword
SourceUnknown
} derive(Eq, Debug)Classification for a single CSP source expression.
#SourceExpressionKind::name
#SourceTrust
Coarse trust bucket used by reports and scoring.
#audit_rules_by_category
#audit_rules_by_severity
#classify_source_expression
#compare_policy_templates
#known_directives_by_category
#recommendation_weight_total
#recommendations_by_priority
fn recommendations_by_priority(items : Array[HardeningRecommendation], priority : RecommendationPriority) -> Array[HardeningRecommendation]MoonBit-native Content-Security-Policy parser, auditor, and diff toolkit.
cspcontent-security-policysecuritypolicy-auditweb
0.1.0
Apache-2.0
Updated 4 hours ago
3 downloads