Reel

구성 가능한 워크플로우, 캠페인 관리 및 선택적 자격 증명 프록시를 갖춘 피싱 시뮬레이션 및 보안 인식 프레임워크.

Quickstart (OPS USE)

1. 저장소를 클론하고 해당 디렉터리로 cd 하세요.
2. ./deploy.sh를 실행하세요. Ubuntu를 사용 중이라면 사전 요구 사항을 자동으로 구성합니다.
3. ./start.sh --preload-ml을 실행하세요. 서버를 시작하고 사용 중인 ML 모델을 미리 로드합니다.

Admin UI는 http://localhost:8000에서, 피싱 서버는 http://localhost:1234에서 확인할 수 있습니다. 기본 로그인: admin / admin123. 첫 로그인 후 비밀번호를 변경하세요.

SSH를 통해 8000 포트를 로컬로 포워딩하여 관리자 패널에 접근하세요. 관리자 패널이나 flask 서버(포트 1234)를 인터넷에 직접 노출하지 마세요.

deploy.sh는 동일한 호스트에 caddy 서버를 설치합니다. 모든 것은 caddy를 리버스 프록시로 사용할 것을 전제로 구성됩니다. 반드시 사용할 필요는 없지만, 사용하지 않으면 문제가 발생할 수 있습니다.

start.sh의 선택적 플래그:

• --with-caddy — Docker를 통해 Caddy를 시작합니다(로컬 테스트 전용).
• --preload-ml — 피싱 탐지 모델을 미리 다운로드합니다(~1.3GB). Phishing Detector 플러그인 사용 시 첫 실행 지연을 방지합니다.
• --reset-db — 데이터베이스를 리셋하고 다시 초기화합니다.
• --admin-only — 관리자 서버(포트 8000)만 시작합니다.
• --phishing-only — 피싱 서버(포트 1234)만 시작합니다.
• --skip-init — 데이터베이스 초기화를 건너뜁니다.
• --skip-setup — venv/종속성 설정을 건너뜁니다. .env를 로드하고 서버만 시작합니다.

start.sh 없이도 종속성을 설치하고 데이터베이스를 초기화한 후에는 uv run python -m cli start로 두 서버를 모두 실행할 수 있습니다.

종속성

Python: requirements.txt를 참조하세요. 핵심 스택에는 Flask, SQLAlchemy, Jinja2, Pydantic, Flask-Login, python-jose, passlib, cryptography 및 Flask-WTF가 포함됩니다. Phishing Detector 플러그인은 transformers와 torch를 사용합니다. 자격 증명 프록시는 Playwright를 사용하며, 선택적 통합은 OpenAI/Anthropic 및 boto3(AWS Connect)를 사용합니다.

개발: requirements-dev.txt에는 pytest, pytest-cov 및 관련 테스트 도구가 추가됩니다. 테스트 및 커버리지 실행을 위해 uv pip install -r requirements-dev.txt로 설치하세요.

시스템(프로덕션): 배포 스크립트는 Ubuntu/Debian을 대상으로 합니다. uv, Caddy(리버스 프록시) 및 libmagic1과 같은 시스템 패키지를 설치합니다. 자격 증명 프록시의 경우 start.sh가 Chromium을 설치하기 위해 uv run playwright install chromium을 실행합니다.

스크립트

deploy.sh

Ubuntu에서의 프로덕션 준비. 멱등(idempotent)합니다. 수행 내용:

1. Ubuntu/Debian을 확인합니다.
2. 시스템 패키지(curl, ca-certificates, libmagic1 등)를 설치합니다.
3. uv가 없으면 설치합니다.
4. 리버스 프록시로 Caddy를 설치합니다(APT).
5. 가상 환경을 만들고 requirements.txt에서 Python 종속성을 설치합니다.
6. .env가 없으면 .env.example에서 생성하고, SECRET_KEY와 JWT_SECRET_KEY가 설정되지 않은 경우 생성합니다.
7. 필요한 디렉터리를 생성합니다(storage/caddy/data, storage/caddy/config, storage/uploads, storage/templates, storage/assets, instance).
8. 선택적으로 --init-db로 데이터베이스를 초기화합니다(uv run python -m cli init --force 실행).

애플리케이션을 시작하지는 않습니다. 프로덕션에서는 Caddy(리버스 프록시)를 시작한 다음 ./start.sh 또는 프로세스 매니저로 앱을 시작하여 모든 트래픽이 프록시를 통해 앱에 도달하도록 하세요.

start.sh

개발 및 로컬 시작용입니다. 수행 내용:

1. .env를 로드하고 SECRET_KEY와 JWT_SECRET_KEY를 확인합니다(기본값이 있으면 생성합니다).
2. uv 설치 여부를 확인합니다.
3. 가상 환경이 없으면 생성합니다.
4. requirements.txt에서 종속성을 설치합니다.
5. 자격 증명 프록시를 위해 uv run playwright install chromium을 실행합니다.
6. 선택적으로 --preload-ml로 피싱 탐지 모델을 미리 다운로드합니다(~1.3GB).
7. 데이터베이스 파일이 없으면 데이터베이스를 초기화합니다(--skip-init이 아닌 경우). --reset-db로 삭제 후 다시 초기화할 수 있습니다.
8. 선택적으로 --with-caddy로 Docker를 통해 Caddy를 시작합니다(로컬 테스트 전용).
9. 서버를 시작합니다: 기본적으로 uv run python -m cli start로 관리자 서버와 피싱 서버를 모두 시작하며, --admin-only 또는 --phishing-only로 하나만 실행할 수 있습니다.

프로덕션 배포

프로덕션에서는 애플리케이션이 반드시 리버스 프록시 뒤에서 실행되어야 합니다. Flask 개발 서버를 인터넷에 직접 노출하지 마세요.

리버스 프록시는 TLS 종료, 올바른 Host 헤더, 경로 및 도메인 라우팅, 관리자 트래픽과 캠페인 트래픽 분리를 담당합니다. 앱은 localhost 또는 내부 포트에서 수신 대기하며, 프록시가 공개 HTTPS를 처리하고 구성에 따라 관리자 서버(예: 포트 8000)와 피싱 서버(예: 포트 1234)로 전달합니다.

권장사항: Caddy를 리버스 프록시로 사용하세요. deploy.sh는 APT를 통해 Caddy를 설치합니다. 프로젝트에는 Caddyfile 예제(예: Caddyfile.minimal)가 포함되어 있습니다. deploy.sh 실행 후 Caddy를 시작하고(예: caddy run --config /path/to/Caddyfile.minimal) 그다음 ./start.sh 또는 프로세스 매니저로 애플리케이션을 시작하세요. 앱이 직접 노출되지 않는 한 동등한 리버스 프록시(nginx, Traefik 등)도 사용 가능합니다.

프로젝트 목적

Reel은 피싱 시뮬레이션 및 보안 인식 프레임워크입니다. 운영자는 admin UI를 사용하여 캠페인, 워크플로우, 템플릿 및 대상을 관리합니다. 피싱 서버는 캠페인 랜딩 페이지를 제공하고 각 요청에서 플러그인의 노드 기반 그래프인 워크플로우를 실행합니다.

app.py에는 두 개의 애플리케이션 진입점이 있습니다: 피싱 서버용 create_app()과 admin UI용 create_admin_app()입니다. 캠페인은 인바운드(방문자가 링크를 따라감; GET 및 POST 워크플로우가 페이지 조회와 양식 제출을 처리) 또는 아웃바운드(시스템이 전송 워크플로우를 통해 이메일이나 전화를 발송)일 수 있습니다. Caddy는 캠페인의 도메인 기반 라우팅에 사용할 수 있습니다. 자격 증명 프록시는 Playwright를 사용한 브라우저 자동화로 대상 사이트에서 캡처된 자격 증명을 재생(replay)합니다.

워크플로우 개념

인바운드

사용자가 캠페인 URL(예: /<campaign_uid>)을 방문합니다. 피싱 서버는 캠페인 UID로 라우팅합니다. GET 요청에는 캠페인의 GET 워크플로우(예: 랜딩 페이지 렌더링, CAPTCHA)를 실행하고, POST 요청에는 POST 워크플로우(예: 입력 검증, 자격 증명 캡처, 리다이렉트)를 실행합니다. 워크플로우는 campaign 유형이며 HTTP 메서드 지원(GET, POST 또는 BOTH)을 선언합니다. 실행 컨텍스트에는 campaign, request, session 및 variables가 포함됩니다. 응답은 _response_html, _response_redirect 또는 _response_json과 같은 컨텍스트 키에서 가져옵니다. 인바운드 워크플로우는 랜딩 페이지, CAPTCHA, 자격 증명 캡처, 리다이렉트 및 로깅에 사용됩니다.

아웃바운드

운영자는 admin UI에서 캠페인에 연결된 전송 워크플로우(sending workflow)를 실행합니다. 전송 실행기는 sending 유형의 단일 워크플로우를 실행합니다: 대상을 선택하고(예: CSV 또는 추적된 사용자), 선택적으로 콘텐츠를 검증하거나 사전 렌더링한 다음 대상 목록을 반복하면서 이메일을 렌더링하고, 속도 제한을 적용하고, 플러그인(예: SMTP)을 통해 전송합니다. 방문자 GET/POST는 없으며, 워크플로우가 콘텐츠를 생성하여 대상 목록에 전송합니다.

요약:

• 인바운드: 방문자 주도형. GET 및 POST 요청이 캠페인 워크플로우를 트리거합니다. 랜딩 페이지와 양식 처리에 사용됩니다.
• 아웃바운드: 운영자 주도형. 단일 전송 워크플로우가 관리자 컨텍스트에서 실행되어 대상(이메일, 음성 등)에게 일괄 전송합니다.

워크플로우 변수

워크플로우를 작성할 때 보간에는 {{variable}} 구문을 사용하세요. 중첩 경로는 점 표기법을 사용합니다: {{nested.key}}.

대상 데이터(CSV / 루프에서)

CSV 예시: email,first_name,last_name,company,landing_page → {{target.email}}, {{target.first_name}}, {{target.company}}, {{target.custom_data.landing_page}}를 사용하세요.

캠페인 / 구성

URL

URL 난독화 도구: 소스로 url 또는 target.landing_page를 사용하거나 보간하세요: http://{{target.ip}}/login.

HTML / BERT 피싱 탐지기

Phishing Detector: html_content를 {{template_html}}, {{campaign.template_html}} 또는 {{email_html}}로 설정하세요.

플러그인 출력

간단한 전송 워크플로우 예시

Target Selector (CSV) → Loop (array_source: targets, item_key: target) → Render Template → SMTP Sender

템플릿의 일반적인 태그: {{target.email}}, {{target.first_name}}, {{target.last_name}}, 그리고 기타 CSV 열용 {{target.custom_data.X}}.

플러그인

워크플로우는 노드로 구성되며 각 노드는 구성이 포함된 플러그인입니다. 다음의 내장 플러그인을 사용할 수 있습니다.

개발

• 테스트 실행: make test-fast 또는 ./run_tests.sh
• 커버리지 포함 테스트: make test-coverage 또는 ./run_tests.sh --coverage
• 린트: make lint
• 포맷 확인: make format-check

추가 타겟(단위/통합/기능 테스트 분할, DB 초기화/리셋, 관리자 또는 피싱 서버만 실행)은 Makefile을 참조하세요.

문서

• DEVELOPMENT.md — 사용자 지정 플러그인 개발을 위한 상세 지침.
• AGENT_README.md — AI 에이전트용: 코드베이스 개념, 플러그인 시스템, 스타일 가이드 및 프롬프트.