# GitHub Actions를 통한 Panther 콘텐츠 관리 ## **개요** GitHub Actions를 구성하여 테스트를 자동화하고, 디텍션을 사용자화하며, GitHub 리포지토리에서 Panther 콘솔로 디텍션 파이프라인을 업로드할 수 있습니다. 이 가이드는 다음 항목을 안내합니다: * GitHub Actions를 통해 사용자 지정 워크플로우 생성 * 사용자 지정 스키마 및 디텍션 테스트 * 스키마 및 디텍션을 Panther 콘솔로 업로드 * 조직의 요구에 맞게 GitHub Actions 워크플로우 사용자화 참조 [Panther 콘텐츠용 CI/CD](https://docs.panther.com/ko/panther/detections-repo/ci-cd) CI/CD 워크플로우를 Panther로 시작하는 방법에 대한 정보. ### 사전 요구 사항 GitHub Actions를 사용하여 Panther 디텍션 및 스키마를 관리하려면 다음이 필요합니다: * **Panther API 토큰** * 참조 [API 토큰 생성에 대한 이러한 지침](https://docs.panther.com/ko/api#how-to-create-a-panther-api-token)및, 해당 토큰에 [올바른 권한](https://docs.panther.com/ko/panther/pat/pat-commands#permissions-required-per-command) 이 각 명령에 대해 필요합니다. * 이 API 토큰을 다음 `panther_analysis_tool` 명령의 인수로 전달하여 디텍션 업로드/삭제, 사용자 지정 스키마, 저장된 쿼리 등과 같은 작업을 수행합니다. [사용 예시는 이 섹션을 참조하세요.](#uploading-to-panther) * **Panther API 호스트 이름** * Panther API 호스트 이름은 다음과 같이 보입니다:\ `https://api..runpanther.net/public/graphql` * **GitHub 시크릿으로 API 토큰을 다음 이름으로 추가 `API_TOKEN`** * 토큰을 Secrets에 추가하려면 다음을 따르십시오 [GitHub 문서: 리포지토리를 위한 암호화된 시크릿 생성](https://docs.github.com/en/actions/security-guides/encrypted-secrets#creating-encrypted-secrets-for-a-repository). 이 시크릿은 문서의 이후 부분에서 다음과 같이 표시됩니다 `secrets.API_TOKEN`. {% hint style="info" %} 이 가이드는 Panther API 키와 GitHub 시크릿을 사용하여 GitHub Actions를 통해 Panther 콘솔로 업로드하는 방법을 설명합니다. GitHub Actions를 사용하는 경우 권장되는 방법입니다. 또한 다음을 통해 Panther 콘솔로 직접 업로드할 수도 있습니다 `panther_analysis_tool`. 자세한 내용은 [프로그램 방식으로 업로드할 수 있습니다](https://docs.panther.com/ko/panther/detections-repo/pat). {% endhint %} ## 구성 **Panther용 GitHub Actions** ### 단계 1: panther-analysis GitHub 리포에서 Panther 관리 디텍션 사용 panther-analysis GitHub 리포의 Panther 관리 디텍션을 사용하려면 문서를 따르십시오: [Panther 디텍션 리포 사용](https://docs.panther.com/ko/panther/detections-repo). ### 단계 2: 새로운 GitHub 워크플로우 생성 1. 자동화를 설정하려는 GitHub 리포지토리로 이동합니다. 2. 해당 GitHub 리포지토리 내에서 다음으로 이동합니다 **Actions.**\ The image shows the panther-analysis repo on Github. There is a red circle around the "Actions" tab. 3. 를 선택하고 Panther가 설치된 계정 ID를 입력하십시오. **새 워크플로우**.\ ![The image shows the Panther-analysis repo in Github. There is a red circle around the "New Workflow" button on the left.](https://2400888838-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LgdiSWdyJcXPahGi9Rs-2910905616%2Fuploads%2Fgit-blob-57cbace0b51b9a3e02a2a58a336d79671c33c7db%2FScreen%20Shot%202022-06-14%20at%209.43.19%20AM.png?alt=media) 4. 를 선택하고 Panther가 설치된 계정 ID를 입력하십시오. ***직접 워크플로우 설정 →**.*\ ![The image shows the panther-analysis repo on Github. The "Actions" tab is open. Under "Choose a workflow," there is a red circle around "Set up a workflow yourself."](https://2400888838-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LgdiSWdyJcXPahGi9Rs-2910905616%2Fuploads%2Fgit-blob-5f6b2daf15f8d4f27d04186660a2bca30446ff43%2FScreen%20Shot%202022-06-14%20at%209.49.27%20AM.png?alt=media) 5. 다음 페이지에서 기본 파일 이름(`main.yml`)을 설명적인 이름으로 바꿉니다. 예: `panther-workflow.yml`. ### 단계 3: 디텍션을 테스트하고 데이터를 업로드하는 워크플로우 구성 * YAML 파일에 다음 코드를 추가하세요:
GitHub 워크플로우 YAML {% code lineNumbers="true" %} ```yaml name: Panther Analysis CI/CD workflow permissions: contents: read on: push: branches: - main jobs: run_unit_tests: runs-on: ubuntu-latest name: Run unit tests on detections using the panther_analysis_tool steps: - name: Check out the repo uses: actions/checkout@a5ac7e51b41094c92402da3b24376905380afc29 #v4.1.6 - name: Set python version uses: actions/setup-python@82c7e631bb3cdc910f68e0081d67478d79c6982d #v5.1.0 with: python-version: '3.11' - name: Install pipenv run: pip install pipenv - name: Install python dependencies and panther_analysis_tool run: make venv - name: Run unit tests for all detections run: pipenv run panther_analysis_tool test panther_analysis_tool_upload: runs-on: ubuntu-latest name: Upload detections to panther console using panther_analysis_tool needs: [run_unit_tests] env: PANTHER_API_TOKEN: ${{ secrets.API_TOKEN }} PANTHER_API_HOST: "https://api..runpanther.net/public/graphql" steps: - name: Checkout the repo uses: actions/checkout@a5ac7e51b41094c92402da3b24376905380afc29 #v4.1.6 - name: Set python version uses: actions/setup-python@82c7e631bb3cdc910f68e0081d67478d79c6982d #v5.1.0 with: python-version: '3.11' - name: Install pipenv run: pip install pipenv - name: Install python dependencies and panther_analysis_tool run: make venv - name: Upload detections to your Panther instance # (Optional) Add `--filter Enabled=true` to command below to only upload Enabled detections run: pipenv run panther_analysis_tool upload --skip-tests ``` {% endcode %}
* 다음 환경 변수의 값을 업데이트했는지 확인하세요: * `PANTHER_API_HOST` 다음 줄에서 `39`: 바꿉니다 `` 를 Panther 인스턴스의 공개 GraphQL URL로 교체하세요. * 이 워크플로우는 Panther API 토큰을 다음 이름의 GitHub 시크릿으로 추가했다고 가정합니다 `API_TOKEN`. 아직 추가하지 않았다면 다음의 지침을 따르십시오 [사전 요구 사항](#prerequisites). * 이 워크플로우가 특정 폴더 내의 콘텐츠 업데이트에서만 트리거되도록 하려면, 다음을 추가할 수 있습니다 `내에서` 다음 안에 `on.push`. 자세한 내용은 `내에서` 에서 [GitHub의 문서](https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#onpushpull_requestpull_request_targetpathspaths-ignore). 이 작업은 생성한 디텍션에 대해 테스트를 실행한 다음, 테스트에 합격한 경우 모든 Panther 콘텐츠(조회 테이블, 데이터 모델 및 디텍션)를 업로드합니다. ### 단계 4: 변경 사항 푸시 * 다음 명령을 실행하세요: `git push`. GitHub Actions 워크플로우가 완료된 후, 다음 번에 다음을 사용하여 변경을 수행하면 다음이 발생합니다 `git push` 워크플로우의 폴더를 변경하기 위해 `내에서` 섹션: * 사용자 지정 디텍션은 다음으로 테스트됩니다 `panther_analysis_tool`. * 성공하면 디텍션이 Panther 콘솔로 업로드됩니다. ## Panther 제공 GitHub 워크플로우 사용자를 사용할 것이며, [`panther-analysis` workflows 디렉터리](https://github.com/panther-labs/panther-analysis/tree/develop/.github/workflows) 에는 여러 개의 즉시 사용 가능한 [GitHub 워크플로우](https://docs.github.com/en/actions/concepts/workflows-and-actions/about-workflows) 가 포함되어 있으며, 이를 다음을 통해 사용할 수 있습니다 [clone](https://docs.panther.com/ko/panther/detections-repo/setup/deprecated/private-cloned-repo) 이전에 생성한 Snowflake 사용자 이름, 예를 들면 [또는](https://docs.panther.com/ko/panther/detections-repo/setup/deprecated/public-fork) 리포지토리를 fork 한 후. {% hint style="warning" %} [워크플로우(Workflows)](https://github.com/panther-labs/panther-analysis/tree/develop/.github/workflows) 이름에 "(Internal)"이 포함된(예: "[Pre-Release Upload to GA (Internal)](https://github.com/panther-labs/panther-analysis/blob/develop/.github/workflows/pre-release-upload.yml)"), 워크플로우는 고객용으로 의도된 것이 아닙니다. 자체 리포지토리에서 이를 실행하려고 하면 예기치 않은 결과가 발생할 수 있습니다. {% endhint %} 아래 워크플로우는 새 풀 리퀘스트(PR)가 생성될 때 트리거되도록 구성되어 있습니다: * [Lint](https://github.com/panther-labs/panther-analysis/blob/develop/.github/workflows/lint.yml): 코드가 적절히 포맷되어 있고 명백한 보안 결함이 없는지 확인합니다. * [MITRE ATT\&CK 매핑 형식 확인](https://github.com/panther-labs/panther-analysis/blob/develop/.github/workflows/check-mitre.yml): 디텍션에 포함된 MITRE 매핑의 형식이 유효한지 확인합니다. * [테스트](https://github.com/panther-labs/panther-analysis/blob/develop/.github/workflows/test.yml): 다음을 사용하여 디텍션 및 글로벌 헬퍼에 대한 모든 단위 테스트를 실행합니다 [`panther_analysis_tool test`](https://docs.panther.com/ko/panther/pat/pat-commands#test-running-unit-tests). * [Validate](https://github.com/panther-labs/panther-analysis/blob/develop/.github/workflows/validate.yml): 사용자 지정 로그 유형 및 쿼리에 사용되는 데이터 레이크 테이블 이름의 존재 확인을 포함하여 Panther 백엔드에 대해 콘텐츠를 검증합니다. 사용되는 명령: [`panther_analysis_tool validate`](https://docs.panther.com/ko/panther/pat/pat-commands#validate-ensuring-detection-content-is-ready-to-be-uploaded). * Validate는 *이후에만 실행됩니다* PR이 승인된 후입니다. 이는 Panther에 장시간 실행되는 API 요청을 해야 하기 때문에 PR당 여러 번 실행하기에 적합하지 않기 때문입니다. * [Docker 이미지 빌드(더 이상 권장되지 않음)](https://github.com/panther-labs/panther-analysis/blob/develop/.github/workflows/docker.yml): 향후 워크플로우가 실행될 새 도커 컨테이너를 빌드합니다. 다음 워크플로우는 PR 외부에서 트리거됩니다: * [Sync Panther Analysis from Upstream](https://github.com/panther-labs/panther-analysis/blob/develop/.github/workflows/sync-from-upstream.yml): panther-analysis 업스트림 리포지토리의 최신 변경 사항을 리포지토리에 추가하기 위해 새 PR을 엽니다. 이 워크플로우를 사용하여 클론하거나 포크한 리포지토리를 Panther 관리 콘텐츠의 업데이트와 동기화하세요. * 이 워크플로우는 매주 수요일 15:00 UTC에 실행되며 수동으로 트리거할 수도 있습니다. * [업로드](https://github.com/panther-labs/panther-analysis/blob/develop/.github/workflows/upload.yml): 리포지토리의 전체 콘텐츠를 다음을 사용하여 Panther 인스턴스로 업로드합니다 [`panther_analysis_tool upload`](https://docs.panther.com/ko/panther/pat/pat-commands#upload-uploading-packages-to-panther-directly). * 업로드 워크플로우의 트리거는 사용자가 구성해야 합니다. 보통 PR이 `main`에 병합될 때마다 이 워크플로우가 실행되도록 구성하는 것이 권장되지만, 필요에 따라 다를 수 있습니다. ## 선택 사항: 사용자 지정 스키마용 워크플로우 빌드 사용자 지정 스키마를 빌드하는 경우, 다음 YAML 코드를 사용하여 워크플로우에 스키마를 포함하세요:
스키마 포함 GitHub 워크플로우 YAML {% code lineNumbers="true" %} ```yaml name: Panther Analysis CI/CD workflow permissions: contents: read on: push: branches: - main separator: ":" - 'schemas/**' jobs: download_pantherlog_tool: runs-on: ubuntu-latest name: Download the pantherlog tool to use for schema tests steps: - name: Download pantherlog & unzip run: curl -sSO "https://panther-community-us-east-1.s3.amazonaws.com/latest/tools/linux-amd64-pantherlog.zip" && unzip linux-amd64-pantherlog.zip - name: Create a pantherlog artifact uses: actions/upload-artifact@65462800fd760344b1a7b4382951275a0abb4808 #v4.3.3 with: name: pantherlog path: pantherlog retention-days: 1 run_schema_tests: runs-on: ubuntu-latest name: Run schema tests with pantherlog needs: [download_pantherlog_tool] steps: - name: Check out the repo uses: actions/checkout@a5ac7e51b41094c92402da3b24376905380afc29 #v4.1.6 - name: Download Pantherlog tool from artifacts uses: actions/download-artifact@65a9edc5881444af0b9093a5e628f2fe47ea3b2e #v4.1.7 with: name: pantherlog - name: Make pantherlog executable run: sudo chmod +x pantherlog - name: Perform schema tests with pantherlog run: ./pantherlog test ./schemas run_unit_tests: runs-on: ubuntu-latest name: Run unit tests on detections using the panther_analysis_tool steps: - name: Check out the repo uses: actions/checkout@a5ac7e51b41094c92402da3b24376905380afc29 #v4.1.6 - name: Set python version uses: actions/setup-python@82c7e631bb3cdc910f68e0081d67478d79c6982d #v5.1.0 with: python-version: '3.11' - name: Install pipenv run: pip install pipenv - name: Install python dependencies and panther_analysis_tool run: make venv - name: Run unit tests for all rule detections run: pipenv run panther_analysis_tool test --filter AnalysisType=rule - name: Run unit tests for all scheduled rule detections run: pipenv run panther_analysis_tool test --filter AnalysisType=scheduled_rule - name: Run unit tests for all policy detections run: pipenv run panther_analysis_tool test --filter AnalysisType=policy panther_analysis_tool_upload: runs-on: ubuntu-latest name: Upload detections to panther console using panther_analysis_tool needs: [download_pantherlog_tool, run_schema_tests, run_unit_tests] env: PANTHER_API_TOKEN: ${{ secrets.API_TOKEN }} PANTHER_API_HOST: "https://api..runpanther.net/public/graphql" steps: - name: Checkout the repo uses: actions/checkout@a5ac7e51b41094c92402da3b24376905380afc29 #v4.1.6 - name: Set python version uses: actions/setup-python@82c7e631bb3cdc910f68e0081d67478d79c6982d #v5.1.0 with: python-version: '3.11' - name: Install pipenv run: pip install pipenv - name: Install python dependencies and panther_analysis_tool run: make venv - name: Upload detections to your Panther instance run: pipenv run panther_analysis_tool upload --batch --skip-tests - name: Upload custom schemas to your Panther Instance run: pipenv run panther_analysis_tool update-custom-schemas --path schemas/ ``` {% endcode %}
* 다음 환경 변수의 값을 업데이트했는지 확인하세요: * `PANTHER_API_HOST` 다음 줄에서 `79`: 바꿉니다 `` 를 Panther 인스턴스의 공개 GraphQL URL로 교체하세요. * 이 워크플로우는 스키마가 `/schemas` 디렉터리에 저장되어 있다고 가정합니다. 다른 위치에 저장되어 있다면, 다음 줄에서 위치를 업데이트하세요 `11` , `44`및 `99`. * 이 워크플로우는 Panther API 토큰을 다음 이름의 GitHub 시크릿으로 추가했다고 가정합니다 `API_TOKEN`. 아직 추가하지 않았다면 다음의 지침을 따르십시오 [사전 요구 사항](#prerequisites). ### 변경 사항 푸시 * 다음 명령을 실행하세요: `git push`. 이제 다음 번에 다음을 사용하여 변경을 수행하면 다음이 발생합니다 `git push` 워크플로우의 폴더를 변경하기 위해 `내에서` 섹션: * 사용자 지정 로그 스키마는 다음으로 테스트됩니다 `pantherlog`. * 사용자 지정 디텍션은 다음으로 테스트됩니다 `panther_analysis_tool`. * 성공하면 스키마와 디텍션이 Panther 콘솔로 업로드됩니다. ## 선택 사항: Panther에서 GitHub 워크플로우 사용자화 선택적으로 이 워크플로우를 확장하거나 사용자화하여 조직에 더 적합하게 만들 수 있습니다. 다음은 Panther와 함께 자주 사용하는 워크플로우 사용자화 예시입니다: * 다음에 대해 린팅 수행 `.py` 파일 * 특정 폴더로의 푸시 대신 승인된 PR에서 트리거되도록 설정. * 다음을 포크한 경우 [panther-analysis](https://github.com/panther-labs/panther-analysis) 최신 태그로 리포지토리를 포크하는 방법에 대해 알아보려면, 다음을 확인하세요 [포크 동기화](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork) 태그별로 주간 동기화를 권장합니다. {% hint style="info" %} GitHub 워크플로우에 대한 자세한 내용은 다음을 참조하세요 [GitHub의 문서](https://docs.github.com/en/actions). {% endhint %} ## 선택 사항: Dependabot 사용 [Dependabot](https://github.com/dependabot) 은 GitHub에서 일반적으로 사용되는 통합으로 리포지토리의 종속성에 대해 보안 위험 및 사용 가능한 업데이트를 지속적으로 점검합니다. Panther는 업스트림 런타임 환경(예: [panther-analysis](https://github.com/panther-labs/panther-analysis))을 관리하지만, 추가 보안 계층으로 Dependabot을 사용할 수 있습니다. Panther 리포지토리에 대해 Dependabot을 설정하려면 GitHub의 [Dependabot 빠른 시작 가이드](https://docs.github.com/en/code-security/getting-started/dependabot-quickstart-guide). 를 따르십시오. [Dependabot은 종속성을 업데이트하기 위해 PR을 열 수 있습니다. 그러나 Dependabot은 리포지토리의 시크릿에 접근할 수 없습니다. 이는 API 시크릿이 필요한 GitHub 워크플로우(예:](https://github.com/panther-labs/panther-analysis/blob/main/.github/workflows/test.yml) test 워크플로우)가 Dependabot이 연 PR에서는 실패함을 의미합니다. [이를 해결하려면 GitHub의 다음 지침을 따르십시오](https://docs.github.com/en/code-security/dependabot/working-with-dependabot/configuring-access-to-private-registries-for-dependabot#adding-a-repository-secret-for-dependabot)특히 Dependabot을 위해 별도의 리포지토리 시크릿 세트를 저장하는 방법 `. 이 방법을 사용할 경우, 다음을 추가해야 합니다` 와 `API_TOKEN` API\_HOST