h3-cli

NodeZero MCP Server

NodeZero MCP Server를 이제 사용할 수 있습니다. 로컬에서 호스팅되는 MCP Server를 실행하고 관리하여 NodeZero의 Find, Fix, Verify(FFV) 기능을 개발 및 보안 워크플로우에 직접 통합할 수 있습니다.

MCP Readme

h3-cli: Horizon3.ai API용 CLI 도구

h3-cli는 Horizon3.ai API에 접근하기 위한 편리한 CLI(명령줄 인터페이스)입니다. Horizon3.ai API는 Horizon3.ai Portal에서 사용할 수 있는 기능의 일부에 대한 프로그래밍 방식의 접근을 제공합니다. 대략적으로 API를 사용하면 다음을 수행할 수 있습니다:

• 자동 침투 테스트 예약
• NodeZero™ 다운로드 및 실행
• 실행 중인 침투 테스트 상태 모니터링
• 완료 후 침투 테스트 보고서 검색

API는 환경에 대한 주기적 평가를 예약하거나 지속적 통합 빌드 파이프라인의 일부로 침투 테스트를 시작하는 등 다양한 사용 사례에 사용할 수 있습니다.

설치 및 초기 설정

아래 단계를 통해 h3-cli를 빠르게 설치하고 실행할 수 있습니다. 이 지침은 macOS 및 Linux 머신에서 테스트되었으며, 일반적으로 bash를 지원하는 모든 POSIX 호환 시스템에서 작동해야 합니다.

h3-cli를 사용하여 내부(internal) 침투 테스트를 실행할 계획이라면, NodeZero를 실행하는 동일한 Docker Host에 h3-cli를 설치해야 합니다.

Horizon3.ai 계정이 이미 있다고 가정합니다. 계정이 없다면 https://portal.horizon3ai.com/에서 가입하세요.

1. API 키 생성

H3 API에 접근하려면 API 키가 필요합니다. Portal의 User -> Account Settings 메뉴에서 생성할 수 있습니다.

API 키를 생성할 때 해당 권한을 제어하는 역할(role)을 할당해야 합니다. 사용 가능한 역할은 다음과 같습니다:

• User: 기본 읽기/쓰기 권한. API 키로 침투 테스트를 실행하고 결과를 읽을 수 있습니다.
• Read-only: API 키로 침투 테스트 결과를 읽을 수 있지만 침투 테스트를 실행할 수는 없습니다.
• NodeZero Runner: NodeZero Runners를 위해 특별히 설계된 전문화되고 매우 제한된 역할입니다.

h3-cli를 테스트하고 모든 기능을 실험해 보려면 User 역할을 권장합니다. 그 후에는 사용 사례에 따라 더 제한적인 권한을 사용할 수 있습니다. 예를 들어 h3-cli를 NodeZero Runner 설정에만 사용하려면 NodeZero Runner 역할을 사용하는 것이 좋습니다.

동일한 h3-cli 설치 내에서 여러 API 키를 쉽게 관리할 수 있습니다. 자세한 내용은 여기를 참조하세요.

❗ API 키를 안전하게 보관하세요. API 키를 가진 사람은 누구나 H3 계정에 접근할 수 있습니다. API 키는 사용자 이름과 비밀번호가 하나로 합쳐진 것과 같습니다. API 키가 있는 사람은 누구나 어디에서든 계정에 접근할 수 있습니다. h3-cli는 API 키를 $HOME/.h3 디렉토리에 저장합니다. 이 디렉토리는 설치 중에 생성되며, 사용자 본인만 읽거나 쓸 수 있도록 권한이 설정됩니다.

2. h3-cli 설치

셸/터미널 세션에서 다음 git 명령을 실행하여 h3-cli git repo를 머신에 설치하세요.

git clone https://github.com/horizon3ai/h3-cli

이렇게 하면 새 디렉토리 h3-cli가 생성되고 저장소의 내용이 해당 디렉토리로 다운로드됩니다. h3-cli 디렉토리는 git 명령을 실행한 디렉토리에 생성됩니다. h3-cli는 파일 시스템의 어디에든 설치할 수 있습니다.

git이 없다면 위 메뉴에서 저장소를 zip 아카이브로 다운로드하여 파일 시스템의 어디에든 압축을 풀 수 있습니다.

3. h3-cli 설치 스크립트 실행

다음 명령을 실행하여 h3-cli를 설치하고 구성하세요. your-api-key-here를 실제 API 키로 바꾸세요.

cd h3-cli
bash install.sh your-api-key-here

설치 스크립트는 종속성(jq)을 설치하고 $HOME/.h3 디렉토리에 기본 h3-cli 프로필을 생성합니다. API 키는 h3-cli 프로필에 저장됩니다. 디렉토리와 프로필 권한은 다른 사용자(본인 제외)가 읽거나 쓸 수 없도록 제한됩니다.

설치 스크립트는 셸 프로필($HOME/.bash_profile 또는 $HOME/.bash_login 또는 $HOME/.profile, 운영 체제에 따라 다름)을 편집하여 다음 환경 변수를 설정하도록 요청합니다:

• H3_CLI_HOME: h3-cli가 자신과 지원 파일의 위치를 찾는 데 사용하는 환경 변수입니다.
• PATH: 셸 명령을 찾기 위해 검색할 디렉토리를 지정하는 환경 변수입니다.

셸 프로필을 업데이트한 후 다시 로그인하거나 셸 세션을 다시 시작하여 프로필 변경 사항을 적용한 다음, 명령 프롬프트에서 h3를 실행하여 호출할 수 있는지 확인하세요:

h3

모든 것이 올바르게 설치되었다면 h3-cli 도움말 텍스트가 표시되어야 합니다.

h3-cli 업그레이드

우리는 매월 h3-cli의 새로운 기능, 버그 수정 및 기타 업데이트를 릴리스합니다. 아래 방법 중 하나를 사용하여 설치를 업그레이드하세요.

옵션 1: h3 upgrade 명령 사용 (권장)

2023년 6월부터 h3 upgrade 명령을 사용하여 최신 버전의 h3-cli로 업그레이드할 수 있습니다.

ERROR: unrecognized command: "upgrade" 오류가 발생하면 upgrade 명령을 지원하지 않는 이전 버전의 h3-cli를 사용 중인 것입니다. 아래 방법 중 하나를 사용하여 h3-cli를 업그레이드하세요.

옵션 2: easy_install.sh 사용 (h3 upgrade를 사용할 수 없는 경우 권장)

h3-cli의 상위 디렉토리(즉, h3-cli/ 디렉토리를 포함하는 디렉토리)에서 다음 명령을 실행하세요:

curl https://raw.githubusercontent.com/horizon3ai/h3-cli/public/easy_install.sh | bash 

옵션 3: git 사용

git clone으로 저장소를 설치했다면 git pull을 실행하여 최신 버전을 설치하면 됩니다.

옵션 4: zip 다운로드 사용

저장소를 zip 파일로 다운로드했다면 zip 파일을 다시 다운로드하여 같은 위치에 압축을 풀면 됩니다(즉, 기존 h3-cli 설치를 새 zip으로 교체).

현재 버전 확인

2023년 6월부터 다음 명령으로 현재 h3-cli 버전을 확인할 수 있습니다:

h3 version

다음 명령으로 전체 버전 기록과 릴리스 노트를 확인할 수 있습니다:

h3 version -v

시작하기

1. API 연결 확인

다음 명령을 실행하여 API와의 연결을 확인하세요.

h3 hello-world

다음과 같은 응답이 표시되어야 합니다:

{
  "data": {
    "hello": "world!"
  }
}

❗️ 오류 응답이 표시되면 Horizon3.ai Portal의 채팅 아이콘을 통해 H3에 문의하세요.

2. 계정의 침투 테스트 목록 조회

아래 명령은 계정의 침투 테스트 목록을 최신순으로 반환합니다.

h3 pentests 

주어진 검색어와 일치하는 침투 테스트를 필터링하려면 검색어를 매개변수로 전달하세요:

h3 pentests sample

3. 계정의 특정 침투 테스트 조회

계정의 가장 최근 침투 테스트를 조회하려면:

h3 pentest

계정의 특정 침투 테스트를 조회하려면 침투 테스트의 op_id를 매개변수로 전달하세요:

h3 pentest your-op-id-here

여러 h3-cli 명령은 매개변수로 op_id가 전달되지 않는 한 가장 최근 침투 테스트를 기본값으로 사용합니다.

"op"와 "pentest"라는 용어는 종종 같은 의미로 사용됩니다.

4. 침투 테스트 실행

침투 테스트를 실행하려면 op 템플릿(op template) 을 지정해야 합니다. op 템플릿은 범위, 공격 매개변수 및 기타 (선택적) 구성을 포함한 전체 침투 테스트 구성을 지정합니다.

Horizon3.ai는 신규 사용자에게 Default 1 - Recommended라는 기본 op 템플릿을 제공합니다. 이 템플릿은 항상 최신 공격 매개변수와 권장 구성으로 업데이트됩니다. 기본 템플릿은 범위를 정의하지 않으며, 이 경우 NodeZero는 Intelligent Scope 를 사용합니다. NodeZero의 호스트 서브넷이 초기 범위를 제공하고, 침투 테스트 중에 더 많은 호스트와 서브넷이 발견됨에 따라 범위가 유기적으로 확장됩니다. Intelligent Scope 및 기타 배포 옵션에 대한 자세한 내용은 제품 문서를 방문하세요.

숙련된 사용자의 경우 Horizon3.ai Portal에서 사용자 지정 op 템플릿을 만들 수 있습니다. 사용자 지정 op 템플릿을 만들려면 Run a Pentest 모달에서 침투 테스트 구성을 사용자 지정하는 옵션이 표시될 때까지 진행하세요. op 템플릿은 실제로 침투 테스트를 실행하지 않고도 만들 수 있습니다.

기본 op 템플릿과 Intelligent Scope를 사용하여 침투 테스트를 프로비저닝하려면:

h3 run-pentest

JSON 응답에는 새로 생성된 침투 테스트의 세부 정보가 포함됩니다. Horizon3.ai Portal을 확인하거나 h3 pentest를 실행하여 침투 테스트가 프로비저닝 중인지 확인할 수 있습니다.

침투 테스트 생성 시 추가 매개변수를 지정하는 방법은 여러 가지가 있습니다. 자세한 내용은 여기에서 추가 예제를 확인하세요.

❗ 잠깐! 아직 끝나지 않았습니다!

내부(internal) 침투 테스트(기본값)의 경우 침투 테스트가 실행을 시작하기 전에 추가 단계가 필요합니다. 침투 테스트 시작을 완료하려면 NodeZero 다운로드 및 실행에 관한 다음 섹션을 참조하세요.

외부(external) 침투 테스트를 실행하는 경우 h3 run-pentest의 일부로 H3 클라우드에서 NodeZero가 자동으로 실행되므로 침투 테스트를 시작하기 위한 추가 단계가 필요하지 않습니다.

5. NodeZero 실행

❗ ️다음 단계는 내부(internal) 침투 테스트에만 적용됩니다. 외부(external) 침투 테스트의 경우 NodeZero는 H3 클라우드에서 자동으로 실행됩니다.

내부(internal) 침투 테스트를 생성한 후에는 네트워크 내부의 Docker Host에서 NodeZero 컨테이너를 실행해야 합니다. 이 작업은 Docker Host에서 NodeZero Launch Script를 실행하여 수행합니다.

가장 최근에 생성한 침투 테스트에 대해 NodeZero Launch Script를 실행하려면:

h3 run-nodezero

침투 테스트가 실행되었습니다! 모든 명령이 오류 없이 실행되었다면 침투 테스트를 성공적으로 생성하고 실행한 것입니다. NodeZero Launch Script의 출력이 콘솔에 기록되는 것을 볼 수 있습니다. 스크립트는 먼저 시스템이 NodeZero와 호환되는지 확인한 후 NodeZero를 다운로드하고 실행합니다. 침투 테스트가 완료되면 NodeZero가 자동으로 종료됩니다.

NodeZero는 Docker 컨테이너입니다. docker ps를 사용하여 확인할 수 있습니다. 컨테이너 이름은 n0-xxxx 형식입니다.

6. 침투 테스트 보고서 다운로드

침투 테스트가 완료된 후 다음 명령을 사용하여 가장 최근에 생성된 침투 테스트의 모든 PDF 및 CSV 보고서가 포함된 zip 파일을 다운로드하세요:

h3 pentest-reports

위 명령은 현재 디렉토리에 pentest-reports-{op_id}.zip 파일을 다운로드합니다.

사용 사례

• NodeZero Runner를 사용한 자동화된 NodeZero 배포. NodeZero Launch Script를 수동으로 복사+붙여넣기 하지 않고도 NodeZero Runner를 사용하여 Docker Host에 NodeZero를 자동으로 배포하는 방법을 알아보세요.
• 자동화된 스케줄링. 예를 들어 주 1회 또는 월 1회와 같이 정기적인 일정으로 침투 테스트를 자동 실행하는 방법을 알아보세요.
• 자동 주입 자격 증명. NodeZero Runner를 사용하여 정기적으로 예약된 침투 테스트에 자격 증명을 자동으로 주입하는 방법을 알아보세요.
• 침투 테스트 모니터링. h3-cli를 사용하여 침투 테스트를 모니터링하는 방법을 알아보세요.
• 결과 페이지네이션. h3-cli를 사용하여 대용량 결과 집합을 페이지네이션하는 방법을 알아보세요.
• jq를 사용한 JSON 파싱. jq의 강력한 기능을 활용하여 h3-cli의 JSON 응답을 파싱하는 방법을 알아보세요. jq는 특정 필드를 파싱하고, 응답 구조를 출력하며, JSON 응답을 CSV로 변환할 수도 있습니다.

인증 및 h3-cli 프로필

h3 명령을 호출하면 인증이 자동으로 원활하게 처리됩니다. 인증을 위해 명시적으로 수행해야 할 작업은 없습니다. 이 섹션에서는 기본 메커니즘을 설명합니다.

h3-cli는 h3-cli 프로필($HOME/.h3 아래)에서 H3_API_KEY를 읽어 Horizon3.ai API에 인증하고 (임시) 세션을 설정합니다. 세션 토큰(JWT)은 $HOME/.h3 아래에 캐시됩니다. 세션 토큰은 1시간 후에 만료되며, 이 시점에 h3-cli가 자동으로 재인증하고 세션을 다시 설정합니다.

다음 명령을 사용하여 명시적으로 인증할 수 있습니다:

h3 auth

위 명령은 세션 토큰을 출력합니다(그리고 $HOME/.h3 아래에 캐시하기도 합니다). 이미 설정된(만료되지 않은) 세션 토큰이 있으면 h3 auth는 다시 인증하는 대신 해당 세션 토큰을 계속 사용합니다.

h3-cli가 강제로 다시 인증하도록 하려면 force 옵션을 사용하세요:

h3 auth force

h3-cli 프로필

동일한 $HOME/.h3 디렉토리 아래에서 여러 h3-cli 인증 프로필을 관리할 수 있습니다. 각 h3-cli 프로필에는 고유한 API 키가 있습니다.

h3-cli를 처음 설치하면 install.sh에 제공한 API 키로 default라는 초기 프로필이 자동으로 생성됩니다.

다른 API 키로 다른 프로필을 만들려면 다음 명령을 사용하세요:

h3 save-profile my-profile {api-key}

이 명령은 주어진 {api_key}에 대해 $HOME/.h3 아래에 my-profile이라는 프로필을 생성합니다. 현재 셸 세션에서 프로필을 활성화하려면 다음 명령을 사용하세요(앞의 점 .에 유의):

. h3 profile my-profile

현재 활성 프로필은 h3 profile로 확인할 수 있고, 해당 API 키에 대한 세부 정보는 h3 whoami로 확인할 수 있습니다:

h3 profile
h3 whoami

서로 다른 h3-cli 프로필에 여러 API 키를 저장하고 필요에 따라 위 명령을 사용하여 전환할 수 있습니다. 예를 들어 default 프로필로 다시 전환하려면:

. h3 profile default

$HOME/.h3 디렉토리 아래의 h3-cli 프로필 목록을 보려면:

h3 profiles

다음 명령으로 $HOME/.h3 디렉토리에서 프로필을 삭제할 수 있습니다:

h3 delete-profile {name}

이 명령은 로컬 머신의 $HOME/.h3 디렉토리에서 {name} 프로필과 해당 API 키를 제거합니다. API 키를 폐기(revoke) 하지는 않는다는 점에 유의하세요. 로컬 머신에서만 삭제할 뿐입니다. API 키는 Portal에서 폐기할 수 있습니다.

h3-cli로 침투 테스트 실행

이 섹션에는 h3-cli를 사용하여 침투 테스트를 실행하는 추가 예제가 포함되어 있습니다.

침투 테스트를 프로비저닝하는 가장 간단한 방법은 기본 op 템플릿과 Intelligent Scope 를 사용하는 것입니다:

h3 run-pentest

침투 테스트를 프로비저닝하고 로컬 머신에서 NodeZero를 실행하려면(내부(internal) 침투 테스트 전용):

h3 run-pentest-and-nodezero

이는 내부(internal) 침투 테스트에만 적용됩니다. 외부(external) 침투 테스트의 경우 NodeZero는 h3 run-pentest의 일부로 H3 클라우드에서 자동으로 실행됩니다.

외부 침투 테스트에 h3 run-pentest-and-nodezero를 실행하게 되면 해당 과정이 H3 클라우드에서 자동으로 처리되므로 NodeZero를 다운로드하고 실행하는 부분을 건너뜁니다.

사용자 지정 op 템플릿을 사용하여 침투 테스트를 실행하려면 schedule_op_template.graphql에 매개변수로 지정하세요:

h3 run-pentest '{"op_template_name":"your-op-template-here"}' 

기본 op 템플릿을 사용하되 원하는 이름을 지정하려면 선택적 op_name 매개변수를 사용하세요:

h3 run-pentest '{"op_name":"your-op-name-here"}' 

기본 op 템플릿을 사용하되 이름과 범위를 지정하려면 선택적 schedule_op_form 매개변수를 사용하세요:

h3 run-pentest '{"schedule_op_form":{"op_name":"your-op-name-here", "op_param_max_scope": "192.168.0.0/24"}}' 

h3 run-pentest와 h3 run-pentest-and-nodezero는 동일한 모든 선택적 매개변수를 허용합니다.

my-nodezero-runner라는 NodeZero Runner에 침투 테스트를 할당하여 실행하려면:

h3 run-pentest '{"schedule_op_form":{"op_name":"Pentest created via h3-cli and launched via runner", "runner_name":"my-nodezero-runner"}}' 

외부 침투 테스트 실행

외부 침투 테스트용으로 구성된 op 템플릿이 있는 경우:

h3 run-pentest '{"op_template_name":"your-op-template-here"}' 

op 템플릿이 없는 경우 h3 asset-groups로 Asset Group의 uuid를 먼저 조회하여 외부 침투 테스트를 실행할 수 있습니다:

h3 asset-groups

그런 다음 아래 명령을 사용하여 해당 Asset Group에 대해 외부 침투 테스트를 실행하세요. {your-asset-group-uuid}를 Asset Group의 uuid로 바꾸세요:

h3 run-pentest '{"schedule_op_form": {"op_type": "ExternalAttack", "asset_group_uuid": "{your-asset-group-uuid}"}}' 

GraphQL 기반

Horizon3.ai API는 GraphQL로 구동됩니다. 이 CLI 문서 외에도 관련 문서는 다음과 같습니다:

• Horizon3.ai Docs
• GraphQL.org

고급: 직접 GraphQL 쿼리 작성

h3-cli는 직접 GraphQL 쿼리를 실행할 수 있는 간단한 메커니즘을 제공합니다. 먼저 파일에 GraphQL 쿼리를 정의합니다(일반적으로 .graphql 확장자를 사용하지만 필수는 아닙니다). 그런 다음 파일을 h3 gql에 전달합니다:

h3 gql {your-query-file}

예를 들어 my_session.graphql이라는 파일에 다음을 정의하세요:

query {
    session_user_account {
        email
        name
        company_name
    }
}

그런 다음 실행하세요:

h3 gql ./my_session.graphql

GraphQL 서버의 원시 JSON 응답이 표시되어야 합니다. jq를 사용하여 JSON 응답을 보기 좋게 출력할 수 있습니다:

h3 gql ./my_session.graphql | jq .

중요! graphql 파일의 경로를 지정해야 합니다(전체 경로 또는 상대 경로, 예: my_session.graphql만이 아닌 ./my_session.graphql). 그렇지 않으면 h3-cli가 내부적으로 사용하는 graphql 파일과 충돌할 위험이 있습니다.

고급: 매개변수화된 GraphQL 쿼리

GraphQL 쿼리는 h3 gql에 JSON 객체로 전달되는 매개변수를 정의할 수도 있습니다.

예를 들어 my_pentest.graphql이라는 파일에 다음을 정의하세요:

query q($op_id: String!) {
    pentest(op_id:$op_id) {
        op_id
        name
        state
    }
}

이 예제에서 $op_id는 쿼리를 실행하기 위해 제공해야 하는 매개변수입니다. 매개변수는 JSON 객체 내에서 쿼리에 전달됩니다:

h3 gql ./my_pentest.graphql '{"op_id":"your-op-id-here"}' | jq .

your-op-id-here를 실제 op_id로 바꾸세요.