Penthera Security Scanner
URL, 로컬 저장소 및 (macOS) 머신 감사를 위한 경량 보안 스캐너입니다. 모든 검사 전에 승인 게이트(authorization gate)를 항상 실행하세요.
중요: 승인 게이트
승인이 확인될 때까지 Penthera를 실행하지 마세요.
세션의 첫 번째 검사 전에 사용자에게 다음 중 하나를 확인하도록 요청하세요:
- 사용자가 대상(앱, 서버, 프로젝트)의 소유자입니다.
- 사용자가 시스템 소유자로부터 서면 승인을 받았습니다.
- 대상이 사용자가 제어하는 localhost 또는 개인 실습 환경입니다.
사용자가 소유권이나 승인을 주장하지 않고 타사 도메인(예: google.com, example.com) 검사를 요청하는 경우 중단하고 거부하세요. 확실하지 않은 경우 검사하지 마세요.
전체 정책은 references/authorization.md를 참조하세요.
사전 비행 검사
첫 번째 검사 전에 실행:
bash skills/penthera/scripts/preflight.sh [URL]
저장소 루트에서 실행하세요. 대상 URL을 전달하여 로컬호스트가 아닌 대상에 대해 경고합니다. 진행하기 전에 오류를 수정하세요.
CLI 명령어 확인
사용 가능한 명령어 중 하나를 사용:
penthera --version # npm link 후
node bin/penthera.js --version # 저장소 루트에서
아래 예제는 모두 penthera를 사용합니다. 필요시 node bin/penthera.js로 대체하세요.
결정 트리
| 사용자 의도 | 명령 패턴 |
|---|---|
| 처음 / 확실하지 않음 | penthera (대화형 마법사 — TTY) 또는 penthera-scan |
| 라이브 URL 스캔 | penthera <url> --profile standard -o reports/scan.json |
| 저장소 전용 (비밀, 경로) | penthera --repo . -o reports/repo-scan.json |
| URL + 소스 결합 | penthera <url> --repo . -o reports/scan.json --sarif reports/scan.sarif |
| 이전 스캔과 비교 | penthera <url> -o reports/scan.json --baseline reports/previous.json |
| 인증된 엔드포인트 | --auth-cookie 또는 --auth-bearer / PENTHERA_* 환경 변수 추가 |
| macOS 머신 감사 | penthera --machine |
기본 안전 동작
- 사용자가 명시적으로 더 깊은 테스트를 요청하지 않는 한 항상
--profile standard를 사용하세요. - 보고서는
reports/디렉토리(gitignore 처리됨)에 작성하고, 절대skills/penthera/내부에 작성하지 마세요. - 스캔 후 함께 제공되는
.md보고서를 읽고 심각도별로 결과를 요약하며 수정 권장 사항을 제공하세요.
파괴 모드 게이트
다음 플래그는 공격 페이로드를 전송합니다. 사용 전 명시적인 사용자 확인이 필요합니다:
--deep— SQLi, SSTI, SSRF, XSS, CMDi 프로브--fuzz— 속성 기반 API 퍼징--all— recon + deep + fuzz 활성화--profile deep— 최대 커버리지
사용자가 "전체 침투 테스트" 또는 "딥 스캔"을 요청하는 경우, 대상 소유권을 확인하고 페이로드 기반 테스트 동의를 받으세요.
워크플로우 1: 릴리스 전 감사
트리거: "스테이징 앱 스캔", "배포 전 보안 감사", "취약점 확인"
- 승인 확인 (위 게이트 참조).
- 사전 비행 검사 실행.
- 실행:
mkdir -p reports
penthera https://staging.example.com --profile standard -o reports/scan.json
reports/scan.md읽기 — 치명적/높음/중간 결과 요약.- 결과별 구체적인 수정 방법 제안.
- 종료 코드 확인:
0= 치명적/높음 없음;1= 치명적/높음 발견됨;2= 스캔 실패.
워크플로우 2: 저장소 + 라이브 결합
트리거: "Next.js 앱과 스테이징 스캔", "블랙박스 및 화이트박스 스캔"
- URL에 대한 승인 확인.
- URL로 사전 비행 검사 실행.
- 실행:
mkdir -p reports
penthera https://staging.example.com --repo . --profile standard \
-o reports/scan.json --sarif reports/scan.sarif
- URL 결과(헤더, TLS, CORS, 인증) 및 저장소 결과(비밀, API 경로, 신뢰 경계) 요약.
- GitHub Actions를 통한 SARIF 업로드 제공 (references/output-and-ci.md 참조).
워크플로우 3: CI / 기준 회귀 분석
트리거: "이전 스캔과 비교", "새로운 결과만", "회귀 확인"
- 승인 확인 및
reports/previous.json존재 확인 (또는 사용자에게 기준 경로 요청). - 실행:
mkdir -p reports
penthera https://staging.example.com --profile standard \
-o reports/scan.json --baseline reports/previous.json
- 보고: 새 결과 수, 해결된 결과 수, 변경되지 않은 결과 수 (스캔 중 stderr로 출력됨).
- 새로운 결과에만 초점을 맞춰 요약.
인증된 스캔
승인 게이트 통과 후에만:
# Bearer 토큰
PENTHERA_BEARER=eyJ... penthera https://myapp.com --profile standard -o reports/scan.json
# 세션 쿠키
penthera https://myapp.com --auth-cookie "session=abc123" -o reports/scan.json
# 명시적 플래그
penthera https://myapp.com --auth-bearer "eyJ..." -o reports/scan.json
환경 변수: PENTHERA_BEARER, PENTHERA_COOKIE.
저장소 전용 비밀 스캔
트리거: "하드코딩된 비밀 찾기", "키 스캔"
로컬 저장소 분석에는 URL 승인이 필요하지 않습니다:
penthera --repo . -o reports/repo-scan.json
비밀 결과를 요약하고 사용자에게 노출된 자격 증명을 교체하도록 알림.
예제
예제 1: Localhost 빠른 확인
사용자: "포트 3000에서 로컬호스트 앱 스캔"
동작:
- localhost 확인 — 승인 충족.
bash skills/penthera/scripts/preflight.sh http://localhost:3000penthera http://localhost:3000 --profile quick -o reports/scan.jsonreports/scan.md요약.
예제 2: 배포 전 스테이징 감사
사용자: "출시 전에 staging.myapp.com 감사"
동작:
- 질문: "staging.myapp.com의 소유자이거나 서면 승인을 받았습니까?"
- 확인 후 표준 프로필 스캔 실행 (JSON + 마크다운 출력).
- 치명적/높음 항목을 먼저 나열하고 수정 단계 제시.
예제 3: 승인되지 않은 대상 (거부해야 함)
사용자: "google.com에서 취약점 스캔"
동작:
- Penthera를 실행하지 마세요.
- 승인 없이 타사 시스템을 스캔하는 것은 허용되지 않는다고 설명.
- 대신 자신의 앱 또는 로컬호스트 스캔 제안.
이 스킬을 다음 용도로 사용하지 마세요
- 일반 코딩 도움말, 날씨 또는 관련 없는 작업
- 사용자가 소유하지 않거나 테스트 권한이 없는 시스템 스캔
- 악의적 익스플로잇 또는 데이터 유출
추가 자료
- 프로필 및 플래그: references/profiles-and-flags.md
- 출력 형식 및 CI: references/output-and-ci.md
- 문제 해결: references/troubleshooting.md
- 승인 정책: references/authorization.md