통합 위협 인텔리전스 수집·동기화 · 블랙리스트 중앙 관리 · Fortinet 자동 배포 플랫폼 Unified threat-intel aggregation, centralized blacklist management, and Fortinet deployment platform.

여러 외부 위협 인텔리전스 소스에서 IP·도메인·URL 을 수집·정규화해 중앙 블랙리스트로 통합한 뒤, Fortinet 같은 외부 보안 장비로 자동 배포하는 Python 기반 통합 관리 플랫폼입니다. Jinja2 웹 콘솔, REST API, WebSocket 실시간 채널을 단일 진입점으로 제공합니다.

A Python platform that aggregates external threat-intel feeds, normalizes entries into a centralized blacklist, and pushes the resulting address objects to Fortinet-style devices via REST API and WebSocket, exposed through a Jinja2 web console.

1. 수집 (Collection) — 외부 위협 인텔 소스에서 IP / Domain / URL 항목을 주기적·수동으로 가져옵니다. (app/core/routes/api/collection/)
2. 정규화 (Normalization) — app/core/routes/api/blacklist/core.py 가 엔트리를 형식·중복 검사 후 중앙 블랙리스트에 머지합니다.
3. 관리 (Management) — app/core/routes/api/blacklist/management.py 와 batch.py 가 일괄 추가·삭제·TTL 만료를 처리합니다.
4. 배포 (Deployment) — app/core/routes/api/fortinet/core.py 가 Fortinet 장비로 주소 객체를 푸시합니다.
5. 관측 (Observability) — app/core/monitoring/ 의 메트릭·에러 카운터와 dashboard.html 이 상태를 시각화하고 WebSocket 으로 알립니다.
6. 인증 (Auth) — app/core/auth/ 의 JWT/데코레이터/미들웨어가 모든 라우트의 인가를 통제합니다.

English summary: collect from intel sources → normalize and merge into the central blacklist → batch-manage with TTL → push to Fortinet → observe via metrics/dashboard → enforce auth across the stack.

1. app/run_app.py — 로컬 실행·앱 팩토리 진입점.
2. app/core/config.py — 환경 변수, 기본 포트, ENV 모드 정의.
3. app/core/app.py — 블루프린트 등록 순서, 미들웨어 체인.
4. app/core/auth/decorators.py — 라우트 보호 패턴과 권한 매트릭스.
5. app/core/routes/api/collection/sync.py — 위협 인텔 동기화 핵심 로직.
6. app/core/routes/api/blacklist/core.py — 머지·정규화 정책.
7. app/core/routes/api/fortinet/core.py — Fortinet 푸시 프로토콜.
8. app/deployment_validation.py — 배포 직전 점검 시나리오.
9. Makefile — 일상 운영 명령 모음.
10. AGENTS.md (루트) — 코드베이스 운영 규약.

• Python 3.11+
• Docker / Docker Compose (컨테이너 실행 시)
• deploy/.env (Compose 가 자동 로드)

git clone <repo-url> blacklist-service
cd blacklist-service

python -m venv .venv
source .venv/bin/activate
pip install -r app/requirements.txt

cp deploy/.env.example deploy/.env   # 필요 시 시크릿 채우기
export PORT=2542
export ENV=development

python app/run_app.py
# → http://localhost:2542

make setup-hooks     # 1회: pre-commit + husky
make dev             # 빌드 + 핫리로드 개발 환경
make dev-no-build    # 기존 이미지로 빠르게 기동
make dev-prod        # 운영 모드에 가까운 빌드
make logs            # tail 로그
make health          # 헬스 체크

make verify          # 전체 검증
make verify-lint     # Ruff
make verify-types    # mypy
make verify-secrets  # 시크릿 누출 점검
make verify-pre-commit
make verify-quick
make verify-all

make release-dry     # 시뮬레이션 (CHANGELOG, VERSION 확인)
make release         # VERSION bump + 커밋 + 태그

.env 의 주요 키 (실제 키 목록은 app/core/config.py 가 SSoT):

운영 환경에서는 deployment_validation.py 가 누락 시크릿과 ENV 불일치를 부트스트랩 전에 차단합니다.

• 린트: ruff check app/ (라인 길이 120, py311).
• 타입: mypy (mypy.ini).
• 테스트: pytest (app/tests 기준, 마커: unit / integration / security / db / api).
• 커밋: Conventional Commits, commitlint.config.js 로 enforce.
• Pre-commit: Python lint/타입/시크릿 스캔; 프런트엔드는 frontend/ 의 husky 가 ESLint·Prettier.
• 핫리로드: make dev 는 볼륨 마운트 + 앱 자동 재시작을 활성화합니다.

1. 클라이언트가 POST /api/collection/{id}/sync 호출.
2. web_routes → middleware 가 JWT 검증 (auth/decorators.py).
3. collection/sync.py 가 소스 자격증명을 collection/credentials.py 에서 로드.
4. 외부 피드를 가져와 정규화 → blacklist/core.py 머지.
5. 결과 이벤트를 monitoring/metrics.py 에 기록, websocket_routes.py 가 구독자에게 푸시.
6. fortinet/core.py 가 변경분을 Fortinet 으로 배포 → 결과를 /api/fortinet 이력에 저장.
7. dashboard_api.py 가 /monitoring/dashboard 에 요약 반영.

# 전체
pytest

# 마커별
pytest -m unit
pytest -m integration     # 외부 서비스 필요
pytest -m security
pytest -m db
pytest -m api

pyproject.toml 의 addopts = "-v --tb=short" 가 적용됩니다. 새 테스트는 app/tests/ 하위에 test_*.py 명명 규칙을 따르세요.

• OWNERS 파일이 코드 오너십과 리뷰어의 SSoT 입니다.
• 운영/릴리스 의사결정은 OWNERS 의 primary / secondary 그룹이 수행합니다.
• 외부 기여 절차는 CONTRIBUTING.md 를 따릅니다.

• 버그 리포트·기능 요청: 저장소 이슈 트래커를 사용하세요.
• 보안 이슈: OWNERS 의 책임자에게 비공개로 연락합니다.
• 내부 채팅: 운영팀 채널에서 blacklist-service 로 검색.
• 상세 운영 절차: CHANGELOG.md 의 마이그레이션 항목과 app/AGENTS.md 의 런북을 따릅니다.