HexStrike AI — Docker + 원격 MCP

linuxserver.io Kali 기본 이미지 위에 Docker화된 HexStrike AI로, 새로운 원격 스트리밍 HTTP MCP 서버를 추가하여 전체 HexStrike 도구 세트를 로컬 stdio 클라이언트에서만이 아니라 네트워크를 통해(예: Claude Code에서) 구동할 수 있게 합니다.

[!WARNING] 이것은 네트워크를 통해 공격적 보안 도구의 자율 실행을 노출합니다. MCP 엔드포인트에 연결된 클라이언트는 컨테이너의 도구 무기고 전반에 걸쳐 사실상 원격 명령 실행을 수행할 수 있습니다. 격리된 랩 외부에서 실행하기 전에 보안 섹션을 읽으십시오. 항상 HEXSTRIKE_MCP_TOKEN을 설정하고, 신뢰할 수 있는/격리된 네트워크 또는 VPN에서만 실행하며, 명시적으로 테스트 권한을 부여받은 시스템만 대상으로 하십시오.

[!NOTE] 사전 빌드된 이미지는 게시되지 않습니다. 전체 Kali 도구 세트로 인해 이미지가 크고(>10 GB — 빌드 시 약 ~17 GB), Docker Hub나 어떤 레지스트리에도 푸시되지 않습니다. 이 저장소에서 직접 빌드해야 하며( 빠른 시작 참조), Docker 호스트에 충분한 여유 디스크가 있는지 확인하십시오.

목차

• 기능

• 개요

• 아키텍처

• 포트

• 빠른 시작

• Claude Code에서 연결

• 환경 변수

• 영속성

• 웹 데스크톱 접근

• 헬스 체크

• 보안

• 도구 범위

• 업스트림 핀 업데이트

• 크레딧 및 라이선스

Related MCP server: MCP Tools

기능

• 전체 업스트림 HexStrike AI 툴킷 — Flask API를 통해 구동되는 150개 이상의 보안 도구 — Kali 기반 이미지에 사전 설치되어 수동 환경 설정이 필요 없습니다.

• 새로 추가: hexstrike_mcp_http.py — 포트 8889(경로 /mcp)에서 네트워크를 통해 모든 업스트림 @mcp.tool() 정의를 노출하는 스트리밍 HTTP MCP 서버로, 로컬 stdio를 통해서만이 아니라 원격으로 구동할 수 있습니다.

• MCP 엔드포인트를 보호하는 선택적 Bearer 토큰 인증.

• 자동화된 도구 실행과 함께 대화형 작업을 위한 브라우저 접근 가능 KDE 데스크톱(Selkies/KasmVNC, 기본 이미지에서 상속).

• 명시적 서비스 순서를 갖춘 s6-overlay v3 프로세스 감독 — MCP 서비스는 HexStrike API 서버가 종속성으로 정의될 때까지 대기합니다.

• 영속적인 /config 볼륨: 도구별 virtualenv 및 파일 관리자 상태가 컨테이너 재시작 후에도 유지됩니다.

• 재현 가능한 빌드: uv가 Python 환경을 관리하고, 업스트림 소스는 벤더링하지 않고 고정된 git 커밋에서 가져옵니다.

개요

HexStrike AI 업스트림은 두 개의 Python 진입점을 제공합니다:

• hexstrike_server.py — 포트 8888에서 수신 대기하는 Flask API 서버로, subprocess를 통해 150개 이상의 외부 보안 도구를 실행하고 그 결과를 HTTP로 노출합니다(도구 가용성을 보고하는 /health 엔드포인트 포함).

• hexstrike_mcp.py — MCP 도구 호출을 위 API 서버에 대한 HTTP 호출로 변환하는 FastMCP 서버입니다. 업스트림은 stdio 전송에서만 실행하므로, 컨테이너와 같은 머신에 있는 MCP 클라이언트에서만 구동할 수 있습니다.

이 저장소는 hexstrike_mcp_http.py 를 추가합니다. 이 파일은 업스트림의 hexstrike_mcp.py 모듈을 가져와 setup_mcp_server() 함수를 그대로 재사용합니다 — 모든 도구 정의는 변경되지 않습니다 — 하지만 stdio 대신 MCP streamable-HTTP 전송을 통해 포트 8889의 /mcp 경로에서 제공합니다. 이것이 유일한 기능적 차이입니다: 동일한 도구 표면이지만, 같은 위치의 프로세스에서만이 아니라 원격으로(예: 다른 머신에서 실행되는 Claude Code에서) 접근할 수 있습니다.

uv (Astral)가 Python 인터프리터와 종속성 환경을 관리하며, 컨테이너 시작 시 두 프로세스를 실행하는 데 사용됩니다.

아키텍처

• 기본 이미지: lscr.io/linuxserver/kali-linux:latest — 포트 3000(HTTP) 및 3001(HTTPS)에서 브라우저 접근 가능한 KDE 데스크톱(Selkies/KasmVNC), Kali-rolling apt 저장소, s6-overlay v3 init을 제공합니다.

• 추가된 서비스: 기본 이미지의 init 시스템 위에 두 개의 s6-overlay longrun 서비스가 계층화되어 user 서비스 번들에 등록됩니다:

  • root/etc/s6-overlay/s6-rc.d/hexstrike-server — abc 사용자로 uv run --no-sync python hexstrike_server.py --port 8888을 실행합니다.

  • root/etc/s6-overlay/s6-rc.d/hexstrike-mcp — abc 사용자로 uv run --no-sync python hexstrike_mcp_http.py --server http://127.0.0.1:8888 --host 0.0.0.0 --port 8889을 실행합니다. dependencies.d/hexstrike-server 항목은 API 서버 이후에 시작하도록 순서를 지정합니다.

• 업스트림 소스는 벤더링되지 않습니다. Dockerfile은 빌드 시 0x4m4/hexstrike-ai를 git clone하고 고정된 커밋(ARG HEXSTRIKE_REF, 기본값 d689933ff579d839c676c82b231f8e98326c5f04)을 체크아웃하여 hexstrike_server.py, hexstrike_mcp.py, hexstrike-ai-mcp.json만 /app에 복사합니다. 이렇게 하면 저장소가 작게 유지되고 업스트림 업데이트가 한 줄 변경으로 끝납니다.

• Python 환경: uv로 관리되는 CPython 3.12(.python-version으로 고정)이며, pyproject.toml의 종속성은 빌드 시 uv sync --no-dev를 통해 /app/.venv에 설치됩니다.

• 영속성 부트스트랩: root/custom-cont-init.d/10-hexstrike-persist는 longrun 서비스가 시작되기 전에 root로 실행됩니다( 영속성 참조).

포트

빠른 시작

Docker Compose (권장)

모든 구성은 docker-compose.yml에 직접 있습니다 — .env 파일은 없습니다. 첫 실행 전에 environment: 블록을 편집하여 다음을 설정하십시오:

• HEXSTRIKE_MCP_TOKEN — MCP 엔드포인트의 Bearer 토큰. openssl rand -hex 32로 강력한 값을 생성하여 붙여넣으십시오(또는 열린 엔드포인트를 위해 비워 두십시오 — 격리된 네트워크의 랩/CTF 전용).

• CUSTOM_USER / PASSWORD — 웹 데스크톱 기본 인증 로그인.

그런 다음 빌드하고 시작합니다:

# generate a token to paste into docker-compose.yml:
openssl rand -hex 32

docker compose up -d --build

빌드는 크고 느리며, 끌어올 사전 빌드 이미지가 없습니다 — 결과 이미지는 >10 GB(~17 GB) 이므로 어떤 레지스트리에도 게시되지 않으며 로컬에서 빌드해야 합니다. kali-linux-headless 메타패키지와 명명된 도구의 긴 목록을 설치하고, angr / pwntools 휠을 컴파일하며(따라서 이미지에 build-essential + 개발 헤더 포함), 세 개의 Go 도구를 소스에서 빌드하고, rustscan 릴리스 패키지를 다운로드합니다. 첫 빌드는 상당한 시간과 충분한 여유 디스크(약 ~20 GB+ 헤드룸, 반복하는 동안 더)가 필요할 것으로 예상하십시오.

일반 Docker

docker build -t hexstrike-ai:local .

docker run -d \
  --name hexstrike-ai \
  --cap-add=NET_RAW --cap-add=NET_ADMIN \
  --shm-size=1g \
  -p 3000:3000 -p 3001:3001 -p 8888:8888 -p 8889:8889 \
  -v "$(pwd)/config:/config" \
  -e PUID=1000 \
  -e PGID=1000 \
  -e TZ=Etc/UTC \
  -e CUSTOM_USER=kali \
  -e PASSWORD=changeme \
  -e HEXSTRIKE_MCP_TOKEN="$(openssl rand -hex 32)" \
  hexstrike-ai:local

--cap-add=NET_RAW --cap-add=NET_ADMIN 및 --shm-size=1g가 필요합니다 — 이유는 보안 및 docker-compose.yml 주석을 참조하십시오.

Claude Code에서 연결

컨테이너가 실행되면 Claude Code를 포트 8889의 MCP 엔드포인트로 지정하십시오. HEXSTRIKE_MCP_TOKEN이 설정된 경우(강력히 권장 — 보안 참조), 모든 요청에 일치하는 Authorization: Bearer <token> 헤더가 포함되어야 합니다. 엔드포인트는 토큰이 설정되지 않은 경우에만 인증되지 않은 요청을 허용합니다.

프로젝트/사용자 MCP 구성(.mcp.json 또는 Claude Code 설정):

{
  "mcpServers": {
    "hexstrike-ai": {
      "type": "http",
      "url": "http://<HOST>:8889/mcp",
      "headers": { "Authorization": "Bearer <HEXSTRIKE_MCP_TOKEN>" }
    }
  }
}

또는 CLI를 통해:

claude mcp add --transport http hexstrike-ai http://<HOST>:8889/mcp \
  --header "Authorization: Bearer <TOKEN>"

<HOST>를 컨테이너 호스트의 주소/호스트 이름으로, <HEXSTRIKE_MCP_TOKEN> / <TOKEN>을 위에서 생성한 값으로 바꾸십시오. 의도적으로 HEXSTRIKE_MCP_TOKEN을 설정하지 않은 경우 headers / --header 인수를 생략하십시오 — 이 경우 엔드포인트는 열려 있습니다.

Invalid Host header / HTTP 421? MCP streamable-HTTP 전송에는 기본적으로 localhost Host 헤더만 신뢰하는 내장 DNS 리바인딩 보호 기능이 있습니다. 이 이미지는 기본적으로 이 검사를 비활성화하여 IP 또는 호스트 이름으로 LAN을 통해 엔드포인트에 도달할 수 있게 합니다. 대신 이 오류가 표시되면 이 이미지로 업그레이드하거나(기본값이 이미 처리함) HEXSTRIKE_MCP_ALLOWED_HOSTS를 클라이언트가 보내는 정확한 host:port 값으로 설정하십시오.

환경 변수

hexstrike_mcp_http.py는 또한 --server / HEXSTRIKE_SERVER_URL, --path / HEXSTRIKE_MCP_PATH, --timeout / HEXSTRIKE_TIMEOUT, --allowed-hosts / HEXSTRIKE_MCP_ALLOWED_HOSTS 재정의를 허용합니다. 제공된 s6 실행 스크립트는 --server, --host, --port만 전달하며 나머지는 환경 변수 폴백에서 읽거나(따라서 컨테이너에 설정된 HEXSTRIKE_MCP_ALLOWED_HOSTS가 작동함) 내장 기본값(/mcp, 업스트림의 기본 요청 시간 초과, Host 검사 비활성화)을 유지합니다.

영속성 (Persistence)

/config 볼륨은 linuxserver 규칙의 홈 디렉터리이며 컨테이너 재생성 시 유지되는 유일한 경로입니다. cont-init 스크립트 root/custom-cont-init.d/10-hexstrike-persist는 longrun 서비스가 시작되기 전에 root로 실행되며 다음을 수행합니다:

1. /config/hexstrike/envs, /config/hexstrike/files, /config/hexstrike/output을 생성합니다.

2. 업스트림의 하드코딩된 /tmp/hexstrike_envs 및 /tmp/hexstrike_files 경로를 /config/hexstrike/envs 및 /config/hexstrike/files로의 심볼릭 링크로 대체하여, HexStrike가 요청 시 빌드하는 도구별 Python 가상 환경과 파일 관리자 읽기/쓰기 영역이 컨테이너 재시작 후에도 유지되도록 합니다.

3. lsiown을 통해 영속 트리를 abc:abc로 chown합니다 (PUID/PGID 존중).

개별 도구 실행으로 생성되는 동적 /tmp/<tool>_output 디렉터리는 심볼릭 링크되지 않으며 임시로 유지됩니다 — 재시작 후에도 출력을 유지해야 한다면 해당 도구를 명시적으로 /config/hexstrike/output을 가리키게 하세요.

웹 데스크톱 접속

브라우저에서 https://<HOST>:3001/을 열고 위에서 구성한 CUSTOM_USER / PASSWORD 자격 증명으로 로그인하세요 (HTTP 데스크톱은 TLS 없이 포트 3000에서도 사용할 수 있습니다).

상태 확인 (Health Check)

curl http://<HOST>:8888/health

컨테이너 내부의 PATH에서 사용 가능한 것으로 감지된 도구 목록을 HexStrike API 서버가 JSON으로 반환합니다.

보안

[!WARNING] 8889의 MCP 엔드포인트는 연결된 클라이언트가 컨테이너 내부에서 공격적 보안 도구의 실행을 자율적으로 구동할 수 있게 합니다 — 이는 사실상 설계상의 원격 명령 실행이며, 구성한 bearer 토큰으로만 제한됩니다.

• 항상 HEXSTRIKE_MCP_TOKEN을 설정하세요. openssl rand -hex 32로 생성하고 비밀로 유지하세요. 비워 두면 MCP 엔드포인트가 인증 없이 접근 가능해집니다.

• 신뢰할 수 있는/격리된 네트워크 또는 VPN에서만 노출하세요. 포트 8889(또는 8888)를 공개 인터넷에 게시하지 마세요.

• 명시적으로 테스트 권한을 부여받은 시스템만 대상으로 하세요. 이 컨테이너는 활성 스캔, 익스플로잇, 자격 증명 공격 등을 수행할 수 있는 실제 공격적 보안 도구를 포함합니다.

• 컨테이너에는 NET_RAW 및 NET_ADMIN 권한이 부여됩니다 (docker-compose.yml / docker run 예시 참조). 여러 도구 — nmap SYN 스캔, masscan, responder 등 — 가 원시 소켓이 필요하기 때문입니다. 이는 --privileged보다는 제한적이지만 여전히 상당히 상승된 권한입니다. 해당 스캔 유형이 필요할 때만 부여하세요.

• 인증은 최소한의 ASGI 미들웨어 (hexstrike_mcp_http.py의 BearerTokenASGIMiddleware)로 구현되며, Authorization 헤더를 상수 시간 비교로 검사하고 MCP 앱에 도달하기 전에 MCP 경로에 대한 인증되지 않은 요청을 401로 거부합니다 — streamable-HTTP/SSE 응답 스트림을 버퍼링하거나 방해하지 않습니다.

도구 범위 (Tool Coverage)

도구 세트는 선별된 것이지 완전한 목록이 아닙니다:

• kali-linux-headless 메타패키지와 Dockerfile에 명시적으로 나열된 도구 목록 (HexStrike의 /health 엔드포인트가 검사하는 도구 및 일반적인 정찰/웹/익스플로잇 유틸리티) — 예: nmap, masscan, gobuster, feroxbuster, ffuf, dirb, dirsearch, nikto, sqlmap, wpscan, whatweb, wafw00f, hydra, john, hashcat, medusa, evil-winrm, amass, dnsenum, dnsrecon, fierce, theharvester, responder, nuclei, subfinder, httpx-toolkit, arjun, paramspider, hakrawler, getallurls (gau), netexec, enum4linux-ng, smbclient, seclists, wordlists, binwalk, foremost, steghide, exiftool, radare2, gdb.

• 빌드 시 소스에서 컴파일된 후 Go 툴체인이 제거된 세 개의 Go 빌드 도구: katana, dalfox, waybackurls.

• 최신 GitHub 릴리스에서 설치된 rustscan (.deb는 rustscan.deb.zip 자산 안에 포함되어 있으며 빌드가 압축을 푼 후 설치합니다. 최선의 노력 — 자산을 해석할 수 없으면 빌드는 그것 없이 계속됩니다).

업스트림 HexStrike가 참조하는 일부 무겁거나 라이선스가 있는 도구 — Ghidra, IDA, Burp Suite Pro, Maltego, Nessus 및 다양한 클라우드/포렌식 유틸리티 — 는 빌드를 관리 가능하게 유지하기 위해 이 이미지에 설치되지 않습니다.

MCP 도구 필터링 (모델에 더 적은 도구 노출)

업스트림은 약 150개의 MCP 도구를 등록합니다. 이는 일부 모델 제공자의 함수 도구 한도(OpenAI는 약 128개로 제한)를 초과하고, 해당 CLI 바이너리가 설치되지 않아 실패할 수밖에 없는 도구도 노출합니다. 이를 방지하기 위해 MCP 서버는 지원 바이너리가 없는 도구를 숨깁니다 (MCP 프로세스가 도구와 동일한 컨테이너에서 실행되므로 시작 시 which로 확인). 일반적인 빌드는 150개 대신 약 115개의 도구를 노출합니다. 시작 로그에 개수와 숨겨진 목록이 출력됩니다.

컨테이너의 환경 변수로 제어하세요:

업스트림 핀 업데이트

업스트림 소스는 빌드 시점에 ARG HEXSTRIKE_REF(Dockerfile)에 지정된 커밋에서 클론됩니다. 최신 업스트림 변경 사항을 반영하려면 해당 핀을 올리고 다시 빌드하세요:

docker build -t hexstrike-ai:local --build-arg HEXSTRIKE_REF=<new-sha> .

또는 Compose를 사용하는 경우 docker-compose.yml의 build: 키 아래에 있는 args: HEXSTRIKE_REF: 항목의 주석을 해제하고 설정한 다음 docker compose up -d --build를 실행하세요.

크레딧 및 라이선스

• HexStrike AI — 0x4m4 제작 — 이 이미지가 패키징하는 보안 자동화 플랫폼으로, MIT License 하에 배포됩니다. 전체 약관은 업스트림의 LICENSE 파일을 참조하세요.

• linuxserver.io kali-linux 이미지 — Kali 환경과 웹 데스크톱을 제공하는 기본 이미지입니다.