pentest-kb MCP Server

침투 테스트 경험 저장소 MCP 서버. MCP (Model Context Protocol) 기반으로 검색, 추가, 목록 조회 등의 도구를 제공하여 침투 테스트 실무 경험을 축적하고 재사용합니다.

이 프로젝트가 해결하는 문제

배경 문제점:

• 침투 테스트 경험이 메모, 대화 기록, 개인 기억에 분산되어 있어 검색과 재사용이 어렵고, 같은 유형의 문제(예: WAF 우회, 403 우회)를 만나면 종종 다시 검색해야 함

• Agent는 기본적으로 개인 경험 저장소에 접근할 수 없어, 침투 테스트 질문에 답할 때 일반 지식에만 의존할 수밖에 없고 실무 경험의 뒷받침이 부족하여 피상적인 조언을 하기 쉬움

• 경험을 축적할 수 없고, 여러 시나리오에 재사용할 수 없어 개인 또는 팀이 쌓은 지식이 체계를 이루기 어려움

이 프로젝트의 해결 방안:

• 침투 테스트 경험을 PostgreSQL(Supabase) 데이터베이스에 통일되게 축적하여 구조적으로 저장

• MCP 프로토콜을 통해 경험 저장소를 Agent에 연결하여 Agent가 경험을 직접 검색(search_experience), 추가(add_experience), 목록 조회(list_all_experiences)할 수 있게 함

• 검색은 BM25 관련성 정렬(jieba 중국어 형태소 분석) 기반으로 단순 퍼지 매칭보다 정확함

• Agent가 실전 시나리오에서 일반 지식에만 의존하지 않고 개인 경험 저장소를 기반으로 답변하게 함

Related MCP server: Nümtema Private Knowledge MCP

기능

• search_experience(keyword, tags_filter): BM25 관련성 정렬 기반으로 경험 저장소를 검색합니다(승인된 기록만). 중국어 형태소 분석을 지원하며 상위 10개를 반환합니다. tags_filter는 시나리오 태그로 정확히 필터링할 수 있습니다(예: ["WAF绕过"]).

• add_experience(title, detail, scenario_tags, tool_code, tool_type, status): 경험을 추가합니다. status='draft'면 승인 대기 초안으로 저장되고(기본값), status='approved'면 바로 저장됩니다. 쓰기 전에 자동으로 비식별화 검사를 수행합니다(실제 IP, 도메인, 자격 증명, 클라우드 공급업체 AccessKey, JWT, 개인 키, 휴대폰 번호를 감지하고 발견되면 거부).

• list_all_experiences(limit, offset): 경험 저장소의 승인된 모든 기록 제목을 페이지 단위로 나열합니다(기본 페이지당 50개, 최대 200개).

• find_similar(title, detail): 중복 검사. 주어진 내용과 유사한 이미 저장된 기록을 찾습니다.

• get_experience(experience_id): id로 경험 하나의 전체 내용(제목, 상세, 태그, 도구 코드, 상태 등)을 가져옵니다.

• update_experience(experience_id, title, detail, scenario_tags, tool_code, tool_type, status): 경험의 필드를 업데이트합니다(전달된 필드만 업데이트하고 전달되지 않은 필드는 유지됩니다. 수정 전 자동 비식별화 검사 수행).

• list_pending_experiences(): 승인 대기 초안을 나열하고 각 초안이 기존 기록과 중복될 수 있음을 안내합니다.

• approve_experience(experience_id, merge_with_id): 초안을 승인합니다. merge_with_id가 제공되면 지정된 기록에 병합(상세 추가, 태그 병합, 도구 정보 보완)한 후 초안을 삭제합니다.

• reject_experience(experience_id): 초안을 거부합니다(소프트 삭제, 기록은 rejected로 유지되며 복원 가능).

• delete_experience(experience_id): 승인된 경험을 소프트 삭제합니다(상태가 deleted로 바뀌고 검색에서 제외되며 복원 가능).

• restore_experience(experience_id): 소프트 삭제된 기록을 복원합니다(거부된 초안→draft, 삭제된 경험→approved).

• list_deleted_experiences(): 소프트 삭제된 모든 기록(휴지통)을 나열하여 복원하거나 완전히 정리할 수 있습니다.

• purge_experiences(days): 소프트 삭제된 지 지정된 일수를 초과한 기록을 물리적으로 삭제합니다(기본 30일, 복원 불가, 주의).

경험 축적 및 승인

자동 축적 과정에서 장황한 내용과 민감 정보 유출이 발생하지 않도록 "반자동 축적 + 강제 비식별화 + 수동 승인" 프로세스를 채택했습니다:

实战结束 → Agent 生成经验草稿（status='draft'，结构化 + 限长 + 脱敏）
        → 草稿进入待审批状态（不直接入库，不参与检索）
        → 用户审批（list_pending 查看 → approve / reject / merge）
        → 通过后才正式入库（status='approved'）

비식별화 방어선: add_experience는 쓰기 전에 실제 IP 주소, 도메인, 이메일, 자격 증명(중국어 "密码/口令/密钥/账号" 등 포함), 클라우드 공급업체 AccessKey(AWS/Aliyun/Tencent), JWT, 개인 키 블록, 휴대폰 번호를 자동으로 감지하고, 발견되면 쓰기를 거부하며 플레이스홀더(예: <目标URL>, <目标域名>)로 바꿀 것을 요구합니다. 사설/루프백/링크-로컬 등 특수 IP와 화이트리스트 도메인(example.com 등)은 저장이 허용됩니다.

중복 검사 방어선: 승인 시 list_pending_experiences가 각 초안과 중복될 수 있는 기존 기록을 자동으로 안내하며, 사용자는 건너뛰기, 병합, 또는 그대로 추가 중에서 선택할 수 있습니다.

직접 저장 vs 초안 승인: add_experience는 status='approved'를 통한 직접 저장을 지원하며, 사용자가 수동으로 확인한 입력 시나리오에서만 사용됩니다. AI 워크플로(SKILL.md 참조)는 반드시 draft 초안을 생성하고 승인을 거쳐야 하며, 직접 저장할 수 없습니다.

의존성

• Python 3.10+

• mcp(MCP Python SDK)

• psycopg2(PostgreSQL 드라이버)

• jieba(중국어 형태소 분석, 시작 시 루트 디렉터리의 pentest_dict.txt 도메인 사전 자동 로드)

• rank_bm25(BM25 검색 알고리즘)

• PostgreSQL 데이터베이스(예: Supabase)

의존성 설치:

pip install -r requirements.txt

의존성 목록은 requirements.txt에 있습니다(버전 범위가 고정되어 있으며, mcp는 2.x여야 합니다).

데이터베이스 초기화

PostgreSQL(예: Supabase)에서 저장소 루트 디렉터리의 schema.sql을 실행합니다(멱등적이며, 반복 실행 가능):

# 方式一：Supabase 控制台 → SQL Editor → 粘贴 schema.sql 内容执行
# 方式二：命令行（需已配置 psql）
psql "$PENTEST_KB_DB_CONNECTION_STRING" -f schema.sql

테이블 구조는 다음과 같습니다(schema.sql이 유일한 유지 관리 원본이며, README는 SQL을 다시 게시하지 않습니다):

선택 사항: 의미 검색 열(현재 코드에서 사용되지 않음, 예약됨) 벡터 의미 검색을 도입하려면 schema.sql 끝의 주석을 해제하고 실행하세요(pgvector 확장을 먼저 활성화해야 함).

구성

데이터베이스 연결 정보는 환경 변수를 통해 주입됩니다. 코드에 자격 증명을 하드코딩하지 마세요:

MCP 클라이언트 구성

MCP 클라이언트에 서버를 등록하려면 mcp.example.json을 참조하세요:

{
  "mcpServers": {
    "pentest-kb": {
      "command": "python",
      "args": ["/absolute/path/to/pentest_kb_mcp.py"],
      "env": {
        "PENTEST_KB_DB_HOST": "your-supabase-host.pooler.supabase.com",
        "PENTEST_KB_DB_PORT": "5432",
        "PENTEST_KB_DB_NAME": "postgres",
        "PENTEST_KB_DB_USER": "postgres.your-project-ref",
        "PENTEST_KB_DB_PASSWORD": "your-database-password"
      }
    }
  }
}

사용

MCP 클라이언트에서 도구를 호출하면 됩니다. 예:

搜索：search_experience(keyword="WAF绕过")   # BM25 相关性排序
搜索+标签过滤：search_experience(keyword="绕过", tags_filter=["WAF绕过"])   # 只看 WAF 相关
新增（直接入库，仅手动操作）：add_experience(title="Nginx 403 绕过", detail="...", scenario_tags=["WAF绕过"], tool_type="burp", status="approved")
新增草稿：add_experience(title="...", detail="...")   # 默认 status='draft'，待审批
查重：find_similar(title="...", detail="...")
查看单条：get_experience(experience_id="...")
修改：update_experience(experience_id="...", detail="...")   # 只更新传入字段
查看草稿：list_pending_experiences()
审批：approve_experience(experience_id="...")   # 或 merge_with_id 合并
拒绝：reject_experience(experience_id="...")   # 软删除，可恢复
删除：delete_experience(experience_id="...")   # 软删除已审批经验
恢复：restore_experience(experience_id="...")
回收站：list_deleted_experiences()
清理：purge_experiences(days=30)   # 物理删除超期软删记录
列出：list_all_experiences(limit=50, offset=0)   # 分页

Skill 캡슐화

사용자 정의 Skill로 캡슐화되어 있으며, 파일은 프로젝트 루트 디렉터리 SKILL.md에 있습니다. 실행 흐름에 따라 6단계로 구성됩니다:

• 1단계: 의도 판단

• 2단계: 정보 수집 우선

• 3단계: 저장소 조회 트리거

• 4단계: 결과 인용 및 답변

• 5단계: 실행 및 면제 규정

• 6단계: 경험 축적

SKILL.md를 사용자 정의 Skill 디렉터리에 넣으면 로드됩니다.

보안 설명

• 데이터베이스 자격 증명은 환경 변수로만 주입되며, 저장소에는 실제 연결 정보가 포함되어 있지 않습니다

• 데이터베이스 비밀번호를 정기적으로 교체하고, 약한 비밀번호를 사용하지 마세요