Shield4U Cross-Repo 분석

메인 인덱스 | Shield4U | GitHub Org

이 문서는 Shield4U를 개별 레포가 아니라 하나의 파이프라인으로 설명하기 위한 정리입니다. 포트폴리오 관점에서는 “각 서비스가 무엇을 했는가”보다 “어떻게 연결했고 무엇을 검증했는가”가 먼저 보이도록 정리했습니다.

프로젝트 개요

프로젝트명: Shield4U
기간: 2025.08.20 ~ 2025.08.21
팀 규모: 4명
제가 맡은 범위: 팀장, 전체 서비스 구조, 서비스 간 통신 규약, 크롤링, 서비스 연결
핵심 흐름: controller -> crawler -> llm -> scanner -> report
검증 결과: testphp.vulnweb.com 기준 depth 1에서 14개 대상을 자동 수집했고, 5개 취약점을 탐지했으며 확인 결과는 모두 정탐이었습니다.

서비스 구조

flowchart LR
    User["사용자 / API 클라이언트"]
    Controller["controller
    오케스트레이터 · API · UI"]
    Crawler["crawler
    Selenium 기반 수집"]
    LLM["llm
    분석 · 템플릿 생성 · 보고서 생성"]
    Scanner["scanner
    Nuclei 실행"]
    DB["DB
    MariaDB"]
    Service["service
    Docker Compose 운영 허브"]
    API["api-endpoint
    API 스캔 보조"]

    User --> Controller
    Service -. 배포/실행 .-> Controller
    Service -. 배포/실행 .-> Crawler
    Service -. 배포/실행 .-> LLM
    Service -. 배포/실행 .-> Scanner
    Service -. 배포/실행 .-> DB
    Controller --> Crawler
    Crawler --> Controller
    Controller --> LLM
    LLM --> Controller
    Controller --> Scanner
    Scanner --> Controller
    Controller --> DB
    API -. 보조 스캔 .-> Controller

레포별 역할 요약

레포	역할	입력	출력	포트폴리오 포인트
controller	전체 워크플로우 조율	사용자 요청, 각 서비스 결과	상태 전이, 보고서 조회, 다음 단계 호출	중앙 오케스트레이션과 상태 추적
crawler	대상 페이지 수집	시작 URL, depth, 옵션	페이지 구조, 폼, 링크, 공격 벡터 후보	파이프라인의 출발점 설계
llm	분석과 보고서 생성	크롤링 결과, 스캔 결과	분류 결과, 스캔 템플릿, 최종 보고서	LLM을 실제 분석 단계에 넣은 구조
scanner	취약점 검증 실행	LLM이 정리한 스캔 정보	Nuclei 실행 결과	도구 통합과 실행 계층
service	운영 및 배포 허브	각 레포와 환경 설정	Compose 실행 환경	운영 구조와 연결 방식
api-endpoint	API 스캔 보조	API 대상 정보	스캔 보조 결과	보조 기능 확장 가능성
DB	데이터 저장	스캔/보고 데이터	영속화된 결과	상태 추적의 저장 기반

데이터와 상태 흐름

sequenceDiagram
    participant U as 사용자
    participant C as controller
    participant CR as crawler
    participant L as llm
    participant S as scanner
    participant D as DB

    U->>C: 스캔 요청
    C->>D: ScanRequest / TaskProgress 생성
    C->>CR: 크롤링 시작
    CR-->>C: 페이지 구조, 폼, 링크, 공격 벡터 후보
    C->>D: 크롤링 결과 저장
    C->>L: 분석 요청
    L-->>C: 취약점 후보 분류, 템플릿 초안
    C->>D: 분석 결과 저장
    C->>S: 스캔 요청
    S-->>C: 취약점 탐지 결과
    C->>D: 스캔 결과 저장
    C->>L: 보고서 생성 요청
    L-->>C: 최종 보고서
    C->>D: 보고서 저장
    C-->>U: 상태/결과 조회 제공

제가 맡은 범위에서 중심에 둔 설계

먼저 전체 흐름을 controller 중심으로 고정하고, 각 서비스는 자기 책임만 수행하도록 나눴습니다.
서비스 간 통신 규약과 콜백 흐름을 먼저 정한 뒤 구현을 붙여서, 짧은 개발 시간 안에도 연결 우선으로 완성도를 확보했습니다.
crawler 결과를 llm이 분석하고, 그 결과를 다시 scanner 실행으로 넘기는 구조를 통해 단순 크롤러나 단순 스캐너가 아닌 파이프라인형 보안 서비스로 만들었습니다.

이 구조에서 설명할 수 있는 기술 포인트

1. 중앙 오케스트레이션

controller가 요청 시작, 상태 전이, 서비스 호출, 결과 저장을 모두 담당합니다. 덕분에 개별 서비스는 상대적으로 단순하게 유지하면서도 전체 흐름은 한 곳에서 추적할 수 있습니다.

2. 단계 분리

수집, 분석, 실행, 보고를 각각 분리해 두었기 때문에 문제를 잘게 나눠 설명할 수 있습니다. 해커톤처럼 시간이 짧은 상황에서도 병렬 작업과 역할 분담이 쉬워지는 장점이 있었습니다.

3. LLM의 실사용 위치

LLM을 결과 설명용 부가 기능으로 두지 않고, 분석 단계와 보고 단계에 직접 넣었습니다. 이 점이 Shield4U를 단순한 웹 크롤링 도구와 다르게 보이게 만드는 핵심입니다.

4. 상태 추적 중심 설계

단계별 결과를 저장하고 다음 단계로 넘기는 구조라서, 진행 상황을 보여주거나 실패 지점을 특정하기가 상대적으로 쉽습니다. 포트폴리오에서는 이 점이 “작동하는 서비스”로 보이게 만드는 요소입니다.

강점과 한계

강점

전체 파이프라인이 끝까지 연결되어 있어 설계 의도를 결과로 설명할 수 있습니다.
각 레포의 책임이 비교적 분명해 발표할 때 구조 설명이 깔끔합니다.
LLM, 크롤링, Nuclei 스캐닝을 하나의 흐름으로 연결한 점이 차별점입니다.

한계와 남은 과제

해커톤 프로젝트라 인증, 관측성, 운영 자동화는 충분히 다듬지 못했습니다.
서비스 간 통신이 비교적 단순한 HTTP 호출 중심이라, 대규모 확장이나 장애 격리 관점에서는 더 보강할 여지가 있습니다.
결과 품질을 더 끌어올리려면 오탐 관리, 비용 통제, 피드백 루프가 추가로 필요합니다.

김현석(TwoTwo-me)

탐색기

cross-repo-analysis