全面的 PHP 安全库,提供 CSP、安全响应头、CSRF 防护、安全 Cookie、密码验证、输入净化、速率限制、SRI、密钥加载、加密、会话安全、TOTP 双因素认证、签名 URL 和安全事件日志记录。
unsafe-*,HTTPS 优先with*() APIext-domext-libxmlext-sodiumcomposer require zappzarapp/security
use Zappzarapp\Security\Headers\Builder\SecurityHeadersBuilder;
$headers = SecurityHeadersBuilder::recommended()->build();
foreach ($headers as $name => $value) {
header("{$name}: {$value}");
}
use Zappzarapp\Security\Csp\HeaderBuilder;
use Zappzarapp\Security\Csp\Directive\CspDirectives;
use Zappzarapp\Security\Csp\Nonce\NonceGenerator;
$generator = new NonceGenerator();
$csp = HeaderBuilder::build(CspDirectives::strict(), $generator);
header("Content-Security-Policy: {$csp}");
$nonce = $generator->get();
echo "<script nonce=\"{$nonce}\">console.log('Safe!');</script>";
use Zappzarapp\Security\Csrf\CsrfProtection;
use Zappzarapp\Security\Csrf\Storage\SessionCsrfStorage;
$csrf = new CsrfProtection(new SessionCsrfStorage());
// 为表单生成令牌
$token = $csrf->generateToken();
echo '<input type="hidden" name="_token" value="' . $token->value() . '">';
// 提交时验证
if (!$csrf->validateToken($_POST['_token'])) {
throw new Exception('CSRF validation failed');
}
use Zappzarapp\Security\Sanitization\Html\HtmlSanitizer;
use Zappzarapp\Security\Sanitization\Path\PathValidationConfig;
use Zappzarapp\Security\Sanitization\Path\PathValidator;
// 净化 HTML(移除危险标签/属性)
$sanitizer = new HtmlSanitizer();
$safe = $sanitizer->sanitize($userInput);
// 验证文件路径(防止目录遍历)
$validator = new PathValidator(new PathValidationConfig(basePath: '/var/www/uploads'));
if (!$validator->isSafe($userPath)) {
throw new Exception('Invalid path');
}
有关所有模块的详细示例,请参阅文档。
每个模块都有详细的 API 文档,包含类引用、配置选项和代码示例:
本库遵循语义化版本 2.0.0。
Zappzarapp\Security 命名空间中的所有类、接口和方法均视为公共 API,除非标记为 @internal。破坏性变更仅在大版本中发生,移除前至少在一个小版本中给出弃用警告。
版本发布通过 release-please 自动化,并使用 GPG 签名。发布历史请参阅 CHANGELOG.md。
有关漏洞报告和安全注意事项,请参阅 SECURITY.md。
有关开发环境搭建和贡献指南,请参阅 CONTRIBUTING.md。
MIT 许可证 — 详情请参阅 LICENSE 文件。
| 模块 | 描述 | 关键类 |
|---|
| CSP | 内容安全策略响应头构建与违规报告 | CspDirectives、HeaderBuilder、NonceGenerator、CspReportParser |
| Headers | 安全响应头(HSTS、Permissions-Policy 等) | SecurityHeaders、SecurityHeadersBuilder |
| CSRF | 跨站请求伪造防护 | CsrfProtection、CsrfConfig |
| Cookie | 安全 Cookie 处理 | SecureCookie、CookieBuilder、CookieOptions |
| Encryption | XChaCha20-Poly1305 认证加密 | SymmetricEncryptor、EnvelopeEncryptor、EncryptionKey、KeyRingEncryptor |
| Password | 密码验证与哈希 | PasswordPolicy、PwnedPasswordChecker、PepperedPasswordHasher |
| Sanitization | 输入净化(HTML、SQL、URI、路径)及文件上传验证 | HtmlSanitizer、UriSanitizer、PathValidator、UploadValidator |
| RateLimiting | 支持多种算法的速率限制 | DefaultRateLimiter、RateLimitConfig |
| SRI | 子资源完整性哈希生成 | SriHashGenerator、IntegrityAttribute |
| Secrets | 基于 Docker/文件的密钥加载 | SecretLoader、SecretValue、FileSecretSource |
| Session | 会话加固与会话固定攻击防护 | SessionGuard、SessionConfig、SessionConfigurator |
| SignedUrl | 带强制过期时间的 HMAC 签名 URL | UrlSigner、SigningKey |
| TOTP | 基于时间的一次性密码(RFC 6238) | TotpAuthenticator、TotpSecret、ProvisioningUri、RecoveryCodeGenerator |
| Analyzer | 安全响应头分析与审计 | SecurityHeaderAnalyzer、AnalysisResult |
| Scanner | CLI 安全响应头扫描器 | ScanCommand、StreamHeaderFetcher |
| Middleware | 用于无缝框架集成的 PSR-15 中间件 | SecurityHeadersMiddleware、CspMiddleware、CspReportHandler、CsrfMiddleware、DoubleSubmitCsrfMiddleware、RateLimitMiddleware、CorsMiddleware |
| Logging | 安全事件日志记录 | SecurityAuditLogger、SecurityEvent |
| 模块 | 描述 |
|---|
| CSP | 带 nonce 和违规报告的内容安全策略 |
| Headers | HSTS、COOP、COEP、CORP、Permissions |
| CSRF | 令牌模式与验证 |
| Cookie | 安全 Cookie 处理 |
| Encryption | 认证加密、信封 |
| Password | 哈希、策略、泄露检测 |
| Sanitization | HTML、URI、路径净化及文件上传验证 |
| Rate Limiting | 令牌桶、滑动窗口 |
| SRI | 子资源完整性哈希 |
| Secrets | 基于 Docker/文件的密钥加载 |
| Session | 会话加固、指纹识别 |
| Signed URLs | 带过期时间的 HMAC 签名 URL |
| TOTP | 一次性密码、恢复码 |
| Analyzer | 安全响应头审计 |
| Scanner | 用于 CI 的 CLI 响应头扫描器 |
| Middleware | PSR-15 中间件 |
| Logging | 安全事件日志记录 |
| Glossary | 安全术语参考 |