horizon3ai/h3-cliHorizon3.ai API용 CLI 도구
NodeZero MCP Server를 이제 사용할 수 있습니다. 로컬에서 호스팅되는 MCP Server를 실행하고 관리하여 NodeZero의 Find, Fix, Verify(FFV) 기능을 개발 및 보안 워크플로우에 직접 통합할 수 있습니다.
h3-cli는 Horizon3.ai API에 접근하기 위한 편리한 CLI(명령줄 인터페이스)입니다. Horizon3.ai API는 Horizon3.ai Portal에서 사용할 수 있는 기능의 일부에 대한 프로그래밍 방식의 접근을 제공합니다. 대략적으로 API를 사용하면 다음을 수행할 수 있습니다:
API는 환경에 대한 주기적 평가를 예약하거나 지속적 통합 빌드 파이프라인의 일부로 침투 테스트를 시작하는 등 다양한 사용 사례에 사용할 수 있습니다.
아래 단계를 통해 h3-cli를 빠르게 설치하고 실행할 수 있습니다. 이 지침은 macOS 및 Linux 머신에서 테스트되었으며, 일반적으로 bash를 지원하는 모든 POSIX 호환 시스템에서 작동해야 합니다.
h3-cli를 사용하여 내부(internal) 침투 테스트를 실행할 계획이라면, NodeZero를 실행하는 동일한 Docker Host에 h3-cli를 설치해야 합니다.
Horizon3.ai 계정이 이미 있다고 가정합니다. 계정이 없다면 https://portal.horizon3ai.com/에서 가입하세요.
H3 API에 접근하려면 API 키가 필요합니다. Portal의 User -> Account Settings 메뉴에서 생성할 수 있습니다.
API 키를 생성할 때 해당 권한을 제어하는 역할(role)을 할당해야 합니다. 사용 가능한 역할은 다음과 같습니다:
h3-cli를 테스트하고 모든 기능을 실험해 보려면 User 역할을 권장합니다. 그 후에는 사용 사례에 따라 더 제한적인 권한을 사용할 수 있습니다. 예를 들어 h3-cli를 NodeZero Runner 설정에만 사용하려면 NodeZero Runner 역할을 사용하는 것이 좋습니다.
동일한 h3-cli 설치 내에서 여러 API 키를 쉽게 관리할 수 있습니다. 자세한 내용은 여기를 참조하세요.
❗ API 키를 안전하게 보관하세요. API 키를 가진 사람은 누구나 H3 계정에 접근할 수 있습니다. API 키는 사용자 이름과 비밀번호가 하나로 합쳐진 것과 같습니다.
API 키가 있는 사람은 누구나 어디에서든 계정에 접근할 수 있습니다. h3-cli는 API 키를 $HOME/.h3 디렉토리에 저장합니다.
이 디렉토리는 설치 중에 생성되며, 사용자 본인만 읽거나 쓸 수 있도록 권한이 설정됩니다.
셸/터미널 세션에서 다음 git 명령을 실행하여 h3-cli git repo를 머신에 설치하세요.
git clone https://github.com/horizon3ai/h3-cli
이렇게 하면 새 디렉토리 h3-cli가 생성되고 저장소의 내용이 해당 디렉토리로 다운로드됩니다. h3-cli 디렉토리는 git 명령을 실행한 디렉토리에 생성됩니다. h3-cli는 파일 시스템의 어디에든 설치할 수 있습니다.
git이 없다면 위 메뉴에서 저장소를 zip 아카이브로 다운로드하여 파일 시스템의 어디에든 압축을 풀 수 있습니다.
다음 명령을 실행하여 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 upgrade 명령 사용 (권장)2023년 6월부터 h3 upgrade 명령을 사용하여 최신 버전의 h3-cli로 업그레이드할 수 있습니다.
ERROR: unrecognized command: "upgrade" 오류가 발생하면 upgrade 명령을 지원하지 않는 이전 버전의 h3-cli를 사용 중인 것입니다.
아래 방법 중 하나를 사용하여 h3-cli를 업그레이드하세요.
easy_install.sh 사용 (h3 upgrade를 사용할 수 없는 경우 권장)h3-cli의 상위 디렉토리(즉, h3-cli/ 디렉토리를 포함하는 디렉토리)에서 다음 명령을 실행하세요:
curl https://raw.githubusercontent.com/horizon3ai/h3-cli/public/easy_install.sh | bash
git clone으로 저장소를 설치했다면 git pull을 실행하여 최신 버전을 설치하면 됩니다.
저장소를 zip 파일로 다운로드했다면 zip 파일을 다시 다운로드하여 같은 위치에 압축을 풀면 됩니다(즉, 기존 h3-cli 설치를 새 zip으로 교체).
2023년 6월부터 다음 명령으로 현재 h3-cli 버전을 확인할 수 있습니다:
h3 version
다음 명령으로 전체 버전 기록과 릴리스 노트를 확인할 수 있습니다:
h3 version -v
다음 명령을 실행하여 API와의 연결을 확인하세요.
h3 hello-world
다음과 같은 응답이 표시되어야 합니다:
{
"data": {
"hello": "world!"
}
}
❗️ 오류 응답이 표시되면 Horizon3.ai Portal의 채팅 아이콘을 통해 H3에 문의하세요.
아래 명령은 계정의 침투 테스트 목록을 최신순으로 반환합니다.
h3 pentests
주어진 검색어와 일치하는 침투 테스트를 필터링하려면 검색어를 매개변수로 전달하세요:
h3 pentests sample
계정의 가장 최근 침투 테스트를 조회하려면:
h3 pentest
계정의 특정 침투 테스트를 조회하려면 침투 테스트의 op_id를 매개변수로 전달하세요:
h3 pentest your-op-id-here
여러 h3-cli 명령은 매개변수로 op_id가 전달되지 않는 한 가장 최근 침투 테스트를 기본값으로 사용합니다.
"op"와 "pentest"라는 용어는 종종 같은 의미로 사용됩니다.
침투 테스트를 실행하려면 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가 자동으로 실행되므로 침투 테스트를 시작하기 위한 추가 단계가 필요하지 않습니다.
❗ ️다음 단계는 내부(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 형식입니다.
침투 테스트가 완료된 후 다음 명령을 사용하여 가장 최근에 생성된 침투 테스트의 모든 PDF 및 CSV 보고서가 포함된 zip 파일을 다운로드하세요:
h3 pentest-reports
위 명령은 현재 디렉토리에 pentest-reports-{op_id}.zip 파일을 다운로드합니다.
jq를 사용한 JSON 파싱. jq의 강력한 기능을 활용하여 h3-cli의 JSON 응답을 파싱하는 방법을 알아보세요.
jq는 특정 필드를 파싱하고, 응답 구조를 출력하며, JSON 응답을 CSV로 변환할 수도 있습니다.