한국어

← 목록으로

CyberStrikeAI 배포 실기록: 간단한 도구 배포도 디테일이 필요하다

itadol5j

최근 Go로 작성된 AI 네이티브 보안 테스트 플랫폼인 CyberStrikeAI를 만지작거리고 있습니다. '원클릭 배포'니까 clone 받아서 스크립트만 돌리면 끝일 줄 알았는데, 결과적으로 크지도 작지도 않은 함정 몇 개를 밟았습니다. 기억이 생생할 때 전 과정을 기록해 둡니다. 많은 함정은 사실 도구의 문제가 아니라 놓친 디테일 때문이었습니다.

CyberStrikeAI 배포

먼저 이것이 어떤 도구인지부터

CyberStrikeAI의 포지셔닝은 'AI 네이티브 사이버보안 액션 시스템'으로, Go로 작성되었으며 계획, 실행, 사람의 감독, 증거 보관, 리플레이를 하나의 감사 가능한 워크스페이스 안에 담습니다. 핵심 구성에는 Eino 기반 Agent, MCP 네이티브 도구, RAG 지식 베이스, 시각화 워크플로, 공격 체인 모델링 분석이 포함됩니다.

100개 이상의 도구 레시피가 내장되어 전체 킬 체인을 커버합니다. nmap, masscan, rustscan 같은 네트워크 스캔, sqlmap, nikto, gobuster, ffuf 같은 웹 스캔, nuclei, wpscan, dalfox 같은 취약점 스캔, 그리고 서브도메인 열거, API 보안, 컨테이너 보안, 클라우드 보안, 바이너리 분석, 익스플로잇, 패스워드 크래킹, 포렌식, 포스트 익스플로잇 등입니다. 승인된 침투 테스트에 필요한 도구는 대부분 이미 오케스트레이션되어 있습니다.

또한 Burp Suite 플러그인과 브라우저 확장도 있어서 캡처한 트래픽을 바로 플랫폼에 넣어 AI 보조 분석을 받을 수 있습니다. 이 설계는 꽤 영리합니다. 기존 워크플로를 바꿀 필요가 없으니까요.

배포 전 환경 준비

공식 사전 조건은 두 가지이며, 버전이 기준을 벗어나지 않도록 주의하세요.

  • Go 1.25+(go.mod에 명시적으로 요구되는 버전이며, 이보다 낮으면 컴파일 시 바로 오류가 발생합니다)
  • Python 3.10+(일부 도구에 필요합니다. 예: api-fuzzer, http-framework-test)

함정 1: Go 버전입니다. 처음에 시스템 기본 구버전 Go를 썼더니 컴파일 단계에 가서야 오류가 났습니다. 먼저 go version 확인해 보길 권합니다. 부족하면 공식 사이트에서 새 버전을 먼저 설치하세요. 이런 '사전 조건'은 오류가 한참 뒤에 발생하기 때문에 가장 놓치기 쉽습니다.

원클릭 배포: 스크립트가 해주는 일

공식 원클릭 배포 명령어는 아주 간결합니다.

git clone https://github.com/Ed1s0nZ/CyberStrikeAI.git
cd CyberStrikeAI
chmod +x run.sh && ./run.sh

하지만 run.sh가 실제로 하는 일은 생각보다 많으며, 다음 순서로 실행합니다.

  • ✅ Go와 Python 환경 검사 및 검증
  • ✅ Python 가상환경 생성
  • ✅ Python 의존성 설치
  • ✅ Go 의존성 다운로드
  • ✅ 프로젝트 빌드
  • ✅ 서비스 시작

디테일 1: venv는 스크립트가 자동 관리합니다. venv/ 디렉터리는 run.sh가 자동으로 생성하고 유지하며, Python이 필요한 도구(api-fuzzer, http-framework-test 등)는 자동으로 이 환경을 사용합니다. 직접 수동으로 만들면 충돌하기 쉬우니 만들지 마세요.

시작 검증: 반드시 확인할 항목들

스크립트가 끝났다고 브라우저부터 열지 말고 먼저 터미널을 확인하세요.

  • 터미널에 ● ONLINE이 표시되는지 확인하고 뒤에 실제 Web UI 주소가 따라오는지
  • 그 주소 열기: 기본 HTTPS 모드는 로컬 자체 서명 인증서를 사용하므로 브라우저가 경고를 띄우는데, 한 번 수락하면 됩니다
  • 새 설치에는 일회용 관리자 비밀번호가 발급됨: 터미널에 ADMIN SETUP REQUIRED 아래에 표시되며, 로그인한 직후 바로 변경하세요

디테일 2: HTTPS 아니면 HTTP입니다. run.sh는 기본적으로 –https 파라미터로 시작합니다(로컬 자체 서명 TLS, 공식 문서에 따르면 이쪽이 동시성 트래픽에 더 친화적). 순수 HTTP를 원한다면 명시적으로 ./run.sh --http를 지정해야 합니다. 수동으로 시작할 때는 –https를 붙이거나 CYBERSTRIKE_HTTPS=1 환경 변수를 설정하세요.

프로덕션 환경에서는 자체 서명 인증서를 쓰지 말고 config.yaml에서 server.tls_cert_path와 server.tls_key_path를 설정하세요.

함정 2: 프로토콜 불일치 오류입니다. 로그에서 'client sent an HTTP request to an HTTPS server'를 본다면 어떤 클라이언트가 여전히 http://로 TLS 포트에 접근하고 있다는 뜻입니다. URL만 고치고 서버 설정을 건드리지 마세요.

AI 네이티브 보안 테스트 플랫폼

초기 설정: AI 채널은 필수

이 단계를 설정하지 않으면 플랫폼은 설치하지 않은 것과 같습니다. 첫 시작 후 https://127.0.0.1:8080/에 접속하고(포트는 config.yaml의 server.port 기준), System Settings → Basic Settings → AI Channel Configuration으로 들어가 채널을 추가한 뒤 provider, Base URL, API key, model, token 상한을 입력합니다.

config.yaml을 직접 수정할 수도 있으며, 형식은 대략 다음과 같습니다.

ai:
default_channel: openai-main
channels:
openai-main:
provider: openai_compatible
api_key: “${OPENAI_API_KEY}”
base_url: “https://api.openai.com/v1”
model: “gpt-4o”

디테일 3: 기본 채널의 적용 범위입니다. ai.default_channel은 새 세션과 채널을 명시적으로 선택하지 않은 작업에 사용됩니다. 채팅 페이지에서는 세션별로 저장되어 있는 어떤 채널이든 따로 선택할 수도 있습니다. 따라서 모델이 여러 개여도 하나만 설정할 필요가 없습니다.

provider에 openai_compatible을 넣으면 OpenAI 인터페이스와 호환되는 대부분의 서비스를 연결할 수 있습니다. base_url을 https://api.deepseek.com/v1로, model을 deepseek-chat으로 바꿔도 되고 qwen3-max도 마찬가지입니다. 중국산 모델도 자유롭게 붙일 수 있어 매우 친절한 부분입니다.

⚠️ 보안 알림: config.yaml에 실제 키를 커밋하지 마세요. 공식 문서에서도 실제 자격 증명을 커밋하지 말고 환경 변수로 주입하라고 명확히 안내합니다.

업그레이드도 방법이 필요합니다

공식 원클릭 업그레이드 스크립트가 제공되지만, 처음에는 실행 권한을 먼저 부여해야 합니다.

chmod +x upgrade.sh && ./upgrade.sh –yes

하는 일: config.yaml과 data/ 디렉터리 백업 → GitHub Release에서 새 코드 가져오기 → config.yaml의 버전 번호 갱신 → 서비스 재시작.로컬의 tools/, roles/, skills/ 디렉터리는 항상 보존됩니다이 점이 매우 중요합니다. 커스텀 도구 레시피가 덮어써지지 않습니다.

함정 3: 업그레이드 스크립트의 의존성입니다. Release 패키지를 다운로드하려면 curl 또는 wget이 필요하고, 안전한 코드 동기화에는 rsync가 사용됩니다(공식 문서 기준 권장/필수). GitHub API에 요청 제한이 걸렸다면 먼저 export GITHUB_TOKEN="..." 확인한 후 다시 실행하세요.

문제가 생기면 .upgrade-backup/에서 복구하거나, 수동으로 data와 config.yaml을 복사해 넣은 뒤 run.sh를 다시 실행하면 됩니다.

중요한 원칙: 업그레이드 전에 반드시 대상 버전의 release notes를 확인하고, 설정·데이터베이스·API 변경이 포함될 때는 특히 조심하세요. 공식 문서의 실속 있는 한마디가 있습니다. '패치 업그레이드라도 백업은 필수이며, 버전 번호 자체는 호환성 보장이 아닙니다.'

디렉터리 구조 한눈에 보기

각 디렉터리의 역할을 알아야 이후 유지보수에서 길을 잃지 않습니다.

  • cmd/ — 서버, MCP stdio 엔트리, 도구
  • internal/ — Agent, MCP 코어, 핸들러, C2, 보안 실행기
  • web/ — 정적 SPA와 템플릿
  • tools/ — YAML 도구 레시피(100개 이상 예시)
  • roles/ — 역할 설정(12개 이상 사전 정의된 보안 테스트 역할)
  • skills/ — Agent Skills 디렉터리(SKILL.md + 선택 파일)
  • agents/ — 멀티 Agent Markdown(orchestrator.md + 하위 Agent)
  • config.yaml — 런타임 설정
  • run.sh / upgrade.sh — 시작 / 업그레이드 스크립트

보안은 도구가 대신해 주지 않습니다

이 플랫폼은 WebShell 관리, 내장 C2(리스너, 암호화 beacon, 세션, 작업 큐) 같은 고위험 기능을 통합하고 있습니다. 공식 입장은 매우 명확합니다.본인이 소유했거나 명확하게 테스트 승인을 받은 시스템에만 사용할 수 있습니다.

공유 환경이나 프로덕션 환경에서 고위험 도구를 활성화하기 전에 반드시 보안 모델과 하드닝 가이드를 먼저 읽으세요. 도구 호출 차단 기능도 내장되어 있어 MCP 실행 전 설정 가능한 정규식 검사를 수행하며, 기본적으로 정부 도메인 보호가 활성화되어 있습니다.

또한 기본적으로 127.0.0.1만 리슨하며, 서비스를 외부에 노출하려면 반드시 먼저 하드닝을 하세요. 이는 형식적인 말이 아니라 큰 사고를 겪어본 사람만 문서에 적을 수 있는 경고입니다.

침투 테스트 플랫폼 설정

마치며

돌이켜보면 이번 배포 자체는 큰 문제가 없었고, 스크립트가 90%의 일을 해냈습니다. 문서를 찾아보게 만든 원인은 전부 '몰랐던' 디테일이었습니다. Go 버전 기준선, venv를 수동으로 만들면 안 된다는 점, HTTPS 기본 활성화로 인한 프로토콜 불일치, 업그레이드 전 백업, 설정 파일에 키를 넣지 말라는 점 등입니다.

이런 디테일은 하나하나 보면 어렵지 않지만 하나만 놓쳐도 30분씩 막힐 수 있습니다. 도구가 성숙할수록 '문서 읽기'의 이득이 커집니다. 복잡도를 스크립트에 감싸 놓았기 때문에 남은 복잡도는 모두 설정 디테일 속에 있기 때문입니다.

이 프로젝트는 knownsec 404Starlink에 합류했으며 Apache 2.0 라이선스로 오픈소스입니다. 승인된 보안 테스트를 하시는 분들은 한번 시도해 보세요.

원클릭 배포가 원클릭 이해는 아니며, 디테일이야말로 시간을 절약하는 진짜 열쇠입니다.

프로젝트 주소: github.com/Ed1s0nZ/CyberStrikeAI(github.com/AIPentest/CyberStrikeAI로 이전됨)
환경 요구 사항: Go 1.25+ / Python 3.10+
라이선스: Apache License 2.0
⚠️ 승인된 테스트 용도로만 사용