Recon-Scan

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

핵심은 빠른 신호입니다. 스캔을 실행하고, 모듈별 결과를 얻고, AI 요약을 확인한 후 이를 정리된 PDF 보고서로 내보낼 수 있습니다.

이 프로젝트의 특징 (그리고 아닌 것)

• 패시브 리콘입니다. 엔드포인트를 무차별 대입하거나, 퍼징하거나, 능동적인 익스플로잇 로직을 실행하지 않습니다.
• 보안 태세 스냅샷, 트라이지 및 보고에 유용합니다.
• 전체 침투 테스트를 대체하지는 않습니다.

기능

• 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.example이 없으면 .env 생성
• 필요시 .venv 생성
• requirements.txt에서 의존성 설치
• http://localhost:8000에서 핫 리로드로 FastAPI 시작
• Redis 없이 로컬 시작을 쉽게 하기 위해 USE_ARQ_QUEUE=false 강제 설정

Ctrl+C로 중단합니다.

원커맨드 시작 (Docker)

./start-docker.sh

이 명령이 수행하는 작업:

• .env.example이 없으면 .env 생성
• 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
  • 본문 예시:
    • { "target": "example.com" }
    • { "target": "example.com", "byoapi_key": "...", "byoapi_provider": "your_provider" }
  • 참고:
    • byoapi_key는 ALLOW_BYO_API_KEY=true인 경우에만 허용
    • 개인/루프백/예약 대상은 차단됨
    • 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 (기본값: )

기여

기여는 환영합니다. 특히 패시브 리콘 모듈, 보고, 프론트엔드 UX, 테스트 커버리지에 대한 기여를 환영합니다.

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

기여 가이드

참고

• 외부 AI 키가 설정되지 않은 경우 ReconScan은 로컬 대체 요약을 저장합니다.
• SQLite는 로컬 사용을 위한 기본 스토리지 엔진입니다.
• 이 저장소는 의도적으로 가볍고 자체 호스팅에 친화적으로 설계되었습니다.

라이선스

MIT. LICENSE 참조.