Recon-Scan

ReconScan은 FastAPI 백엔드, 비동기 워커 파이프라인, 단일 페이지 프론트엔드로 구성된 오픈소스 패시브 정찰 스캐너입니다. 배포된 사이트는 https://recon-scan.vercel.app/ 에서 확인할 수 있습니다.

핵심은 빠른 신호입니다. 스캔을 실행하고, 모듈별 결과를 확인하고, 이제 세련된 PDF 보고서로 내보낼 수 있는 AI 요약을 받아보세요.

참고: AI 토큰이 소진되어 데모는 라이브 상태가 아닙니다. 직접 호스팅은 여전히 가능합니다.

이 프로젝트가 무엇인지 (그리고 무엇이 아닌지)

• 패시브 정찰입니다. 엔드포인트를 무차별 대입하거나, 퍼징하거나, 능동적 익스플로잇 로직을 실행하지 않습니다.
• 보안 태세 스냅샷, 트리아지, 보고에 적합합니다.
• 전체 모의해킹을 대체하지는 않습니다.

기능

• 13개의 패시브 모듈:
  • 보안 헤더
  • SSL/TLS
  • DNS + 이메일 인증 (SPF/DMARC/MX)
  • WHOIS
  • Robots/sitemap
  • 서브도메인 열거
  • 기술 핑거프린팅
  • WAF 탐지
  • CORS 검사
  • 쿠키 보안 검사
  • JS 노출 검사
  • 디렉터리 노출 검사
  • 평판 검사
• Redis + ARQ 워커를 사용한 비동기 실행.
• 큐 등록 실패 시 인프로세스 백그라운드 실행으로 폴백.
• OpenRouter / Anthropic / OpenAI를 통한 선택적 AI 요약.
• 스캔 + AI 요약으로부터 PDF 보고서 생성.
• FastAPI가 직접 제공하는 프론트엔드 (하나의 URL, 하나의 앱).

원 커맨드 시작 (로컬 개발)

빠르게 실행하고 싶다면:

./start.sh

이 스크립트가 하는 일:

• .env가 없으면 .env.example에서 생성합니다.
• 필요하면 .venv를 생성합니다.
• requirements.txt에서 의존성을 설치합니다.
• http://localhost:8000에서 핫 리로드로 FastAPI를 시작합니다.
• Redis 없이 로컬에서 쉽게 시작할 수 있도록 USE_ARQ_QUEUE=false를 강제합니다.

Ctrl+C로 중지합니다.

원 커맨드 시작 (Docker)

./start-docker.sh

이 스크립트가 하는 일:

• .env가 없으면 .env.example에서 생성합니다.
• Docker Compose로 API + 워커 + Redis를 시작합니다.

Docker 시작 (수동)

cp .env.example .env
docker compose up --build

로컬 개발 (Docker 없이)

1. 의존성 설치:

pip install -r requirements.txt

2. env 파일 생성:

cp .env.example .env

3. API 시작:

uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

4. 다른 터미널에서 워커 시작 (권장):

arq app.worker.WorkerSettings

5. 접속:

http://localhost:8000

테스트 실행

테스트 의존성 설치:

pip install -r requirements-dev.txt

전체 스위트 실행:

pytest -q

PDF 보고서

스캔이 완료되면 UI에서 Download PDF를 클릭하세요.

백엔드 엔드포인트:

• GET /scans/{scan_id}/report.pdf

보고서에 포함되는 내용:

• 대상 및 스캔 메타데이터
• AI 경영진 요약 (가능한 경우 짧은 버전 + 전체 서술)
• 심각도 스냅샷 테이블
• 모듈별 상세 결과

API

• GET /health
• POST /scans
  • body 예시:
    • { "target": "example.com" }
    • { "target": "example.com", "byoapi_key": "...", "byoapi_provider": "your_provider" }
  • 참고:
    • ALLOW_BYO_API_KEY=true가 아니면 byoapi_key는 거부됩니다
    • private / loopback / reserved 대상은 차단됩니다
    • user_id는 선택 사항이며 호환성을 위해 유지됩니다
• GET /scans/{scan_id}
• GET /scans/{scan_id}/report.pdf

구성

.env.example에서:

• DATABASE_URL (기본값: sqlite:///./reconscan.db)
• REDIS_URL (기본값: redis://localhost:6379)
• USE_ARQ_QUEUE (기본값: true)
• RATE_LIMIT_PER_MINUTE (기본값: 10)
• RATE_LIMIT_PER_DAY (기본값: 200)
• ALLOWED_HOSTS (기본값: localhost,127.0.0.1)
• CORS_ALLOWED_ORIGINS (기본값: 로컬 개발 오리진)
• ALLOW_BYO_API_KEY (기본값: false)
• OPENROUTER_API_KEY, ANTHROPIC_API_KEY, OPENAI_API_KEY (선택)
• VIRUSTOTAL_API_KEY, GOOGLE_SAFE_BROWSING_API_KEY (선택)

기여

기여를 환영합니다. 특히 패시브 정찰 모듈, 보고, 프론트엔드 UX, 테스트 커버리지와 관련된 부분이 좋습니다.

풀 리퀘스트를 열기 전에 전체 기여 가이드라인을 읽어주세요:

기여 가이드

참고

• 외부 AI 키가 구성되지 않으면 ReconScan은 로컬 폴백 요약을 저장합니다.
• SQLite는 쉬운 로컬 사용을 위한 기본 스토리지 엔진입니다.
• 이 저장소는 의도적으로 가볍고 셀프 호스팅 친화적입니다.

라이선스

MIT. LICENSE를 참조하세요.