⚔️ s0d ⚔️

---

       _______       .___
  _____╲   _  ╲    __│ _╱
 ╱  ___╱  ╱_╲  ╲  ╱ __ │
 ╲___ ╲╲  ╲_╱   ╲╱ ╱_╱ │
╱____  >╲_____  ╱╲____ │
     ╲╱       ╲╱      ╲╱  s0d-scanner

WordPress 플러그인/PHP 코드를 대상으로 분석을 수행하는 규칙 기반 스캐너입니다. Docker 기반으로 실행되며, 로컬 ./targets를 컨테이너 /app/targets에 마운트해 스캔합니다.

📖 목차

• 핵심 경로
• Quick Start
• 실행 방식 요약
• 스캔 대상 넣는법
• 주요 옵션
• 설치/실행 요구사항
• 환경변수
• 룰 추가/수정
• 컨테이너 쉘 접속
• 스캐너 아키텍쳐
• 팀원 소개

🔍 핵심 경로

• 룰: rule-set/ → 컨테이너 /app/rules
• 스캔 대상: targets/ → 컨테이너 /app/targets (read-only)
• 산출물: outputs/, report/ → 컨테이너 /app/outputs, /app/report
• 실행 엔트리: s0d (Docker Compose 래퍼)

🏃 Quick Start

1. 레포지토리 이동

cd /path/to/s0d-scanner

2. 런처 설치 (권장)

chmod +x s0d

# 전역 설치 (기본: /usr/local/bin)
./s0d install

# 또는 사용자 bin 디렉토리에 설치
S0D_INSTALL_DIR="$HOME/bin" ./s0d install

3. 이미지 빌드

s0d build

4. 스캔 실행

# 대화형 모드 (배너 + 모드 선택)
s0d

# 단일 파일 스캔
s0d -f test.php

# 단일 플러그인 디렉토리 스캔
s0d -p my-plugin

# 모든 플러그인 스캔
s0d -ap

↪️ 실행 방식 요약

docker compose run --rm s0d-scanner python3 main.py ...

✅ 스캔 대상 넣는 법

# 로컬 targets/test.php를 스캔
s0d -f test.php

⩤ 주요 옵션

s0d --help

- `-f, --file <path>`: 단일 파일 스캔
- `-p, --plugin <name|path>`: 단일 플러그인 스캔
- `-ap, --all-plugins`: 모든 플러그인 스캔
- `--rules`: 컨테이너 `/app/rules`의 룰 파일 목록 출력
- `-d, --debug`: 디버그 로그까지 콘솔 출력
- `--process <N>`: 멀티프로세싱 프로세스 수 지정
- `-ar, --ai-report`: AI 보고서 생성
- `-nr, --notion-report`: Notion 동기화(플러그인 스캔에서만)
- `-fpfn, --fpfn`: 파일 스캔 시 category 기준 FP/FN 지표 출력

⬇️ 설치/실행 요구사항

• Docker
• Docker Compose

빌드 시 내부에서 다음을 사용합니다.

• PHP 8.2 (컨테이너 내)
• Composer (컨테이너 내)
• Python 3 + venv (컨테이너 내)

🔖 환경 변수(.env)

docker-compose.yml은 루트의 .env 파일을 읽습니다.

1) Notion 리포트

-nr, --notion-report 사용 시 필요합니다.

NOTION_API_KEY=secret_xxx
NOTION_DATABASE_ID=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

2) AI 리포트

기본값은 Ollama를 바라보도록 되어 있습니다.

# provider: ollama | openai(호환) 등
S0D_AI_PROVIDER=ollama

# Ollama 예시
S0D_AI_ENDPOINT=http://host.docker.internal:11434/api/chat
S0D_AI_MODEL=qwen2.5-coder:14b

# OpenAI-호환 provider 예시
# S0D_AI_PROVIDER=openai
# S0D_AI_API_KEY=sk-...
# S0D_AI_ENDPOINT=https://api.openai.com/v1/chat/completions
# S0D_AI_MODEL=gpt-4.1-mini

# 공통 옵션
S0D_AI_TIMEOUT=300
S0D_AI_DEBUG=1
S0D_REPORT_DIR=/app/report

🧾 룰 추가/수정

룰은 rule-set/ 아래의 *.yml, *.yaml을 자동 로드합니다.

• 예: rule-set/test_rule.yml
• 컨테이너 경로: /app/rules

s0d build

🖥️ 컨테이너 쉘 접속

디버깅이 필요하면 아래 방식이 가장 간단합니다.

docker compose run --rm s0d-scanner sh

장기 실행 컨테이너로 붙고 싶다면:

docker compose up -d --build
docker compose exec s0d-scanner sh

---

🏛️ 스캐너 아키텍쳐

Layer (Component)	역할	설명	주요 입/출력(예시)
CLI Interface	사용자 입력/설정 수집	사용자 입력을 받고 스캔 설정을 구성함	Input: target path, 옵션, config Output: scan config, job request
Scanner Core	수집/실행 오케스트레이션	파일 수집과 스캔 실행 흐름을 조율함	Input: scan config Output: file list, scan plan, 실행 결과
PHP Parser & AST Builder	AST 생성	PHP 소스 코드를 JSON AST로 변환함	Input: PHP source files Output: JSON AST
Detection Engine	AST 분석/탐지	카테고리 기반 핸들러로 AST를 분석해 취약점/이슈를 탐지함	Input: JSON AST Output: raw findings (rules hits)
Findings / Report Generator	결과 집계/리포트	findings를 집계하고 리포트를 생성함	Input: findings, metadata Output: report (md/json/html), summary

Scan / Detection Pipeline

단계	입력	처리(무엇을 함)	출력
1) Source Collection	.php 파일들	스캔 대상 파일 수집/선정	PHP 소스 파일 목록
2) AST Build	PHP 소스	PHP Parser & AST Builder가 소스를 JSON AST로 변환	JSON AST
3) Rule Loading	rule-set.yml	룰셋(카테고리/패턴/심각도/메시지 등) 로딩	룰 핸들러/룰 정의
4) Detection Engine	JSON AST + 룰셋	카테고리별 핸들러가 AST를 분석해 룰 매칭 수행	Findings (원시 탐지 결과)
5) Finding Aggregation	Findings	중복 제거/그룹핑/스코어링/증거 연결	Aggregated Findings
6) Reporting (선택)	Aggregated Findings	리포트 생성 (md/json/html 등)	최종 보고서

---

🧑‍🏫 팀원 소개

	김하람	강혜인	노민영	이융현
Profile
Role	Team Leader XSS RCE	Team Member Path_Traversal Request_Forgery	Team Member SQLI PHP_Object_Injection	Team Member File_vulnerability Sensitive_Data_exposure
GitHub	@1unaram	@hhhyenn	@nominyoung	@fostacion

---