⚡ zappzarapp/security

CSP, 보안 헤더, CSRF 보호, 보안 쿠키, 비밀번호 검증, 입력 정화, 속도 제한, SRI, 시크릿 로딩, 암호화, 세션 보안, TOTP 2단계 인증, 서명된 URL 및 보안 이벤트 로깅을 제공하는 포괄적인 PHP 보안 라이브러리입니다.

주요 특징

• 올인원 — 단일 구성 가능한 패키지에 17개의 보안 모듈
• 기본 보안 강화 — 엄격한 CSP, unsafe-* 미사용, HTTPS 우선
• 프레임워크 비종속 — 모든 PHP 8.4+ 애플리케이션에서 작동
• 불변 및 타입 안전 — readonly 클래스, enum, with*() API
• 품질 보증 — PHPStan Level 8, Psalm Level 1, 100% Mutation Score, Deptrac 아키텍처 강제
• PSR 호환 — PSR-3(로깅), PSR-15(미들웨어), PSR-18(HTTP 클라이언트)

모듈

모듈	설명	주요 클래스
CSP	콘텐츠 보안 정책 헤더 생성 및 위반 보고	CspDirectives, HeaderBuilder, NonceGenerator, CspReportParser
Headers	보안 헤더(HSTS, Permissions-Policy 등)	SecurityHeaders, SecurityHeadersBuilder
CSRF	사이트 간 요청 위조(Cross-Site Request Forgery) 보호	CsrfProtection, CsrfConfig
Cookie	보안 쿠키 처리	SecureCookie, CookieBuilder, CookieOptions
Encryption	XChaCha20-Poly1305 인증 암호화	SymmetricEncryptor, EnvelopeEncryptor, EncryptionKey, KeyRingEncryptor
Password	비밀번호 검증 및 해싱	PasswordPolicy, PwnedPasswordChecker, PepperedPasswordHasher
Sanitization	입력 정화(HTML, SQL, URI, Path) 및 파일 업로드 검증	HtmlSanitizer, UriSanitizer, PathValidator, UploadValidator
RateLimiting	여러 알고리즘을 지원하는 속도 제한	DefaultRateLimiter, RateLimitConfig
SRI	하위 리소스 무결성(SRI) 해시 생성	SriHashGenerator, IntegrityAttribute
Secrets	Docker/파일 기반 시크릿 로딩	SecretLoader, SecretValue, FileSecretSource
Session	세션 강화 및 고정(fixation) 보호	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

요구 사항

• PHP ^8.4
• ext-dom
• ext-libxml
• ext-sodium

설치

composer require zappzarapp/security

빠른 시작

보안 헤더

use Zappzarapp\Security\Headers\Builder\SecurityHeadersBuilder;

$headers = SecurityHeadersBuilder::recommended()->build();
foreach ($headers as $name => $value) {
    header("{$name}: {$value}");
}

Nonce 기반 CSP

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>";

CSRF 보호

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 문서가 있습니다: