# GitHub Actions를 통한 Panther 콘텐츠 관리 ## **개요** GitHub Actions를 구성하여 테스트를 자동화하고, 디택션을 사용자 지정하며, GitHub 저장소에서 Panther Console로 디택션 파이프라인을 업로드할 수 있습니다. 이 가이드는 다음 내용을 안내합니다. * GitHub Actions를 통해 사용자 지정 워크플로 만들기 * 사용자 지정 스키마와 디택션 테스트하기 * 스키마와 디택션을 Panther Console에 업로드하기 * 조직의 요구에 맞게 GitHub Actions 워크플로 사용자 지정하기 다음을 참조하세요 [Panther 콘텐츠용 CI/CD](/ko/panther/detections-repo/ci-cd.md) Panther와 함께 CI/CD 워크플로를 시작하는 방법에 대한 정보는 ### 사전 요구 사항 GitHub Actions를 사용하여 Panther 디택션과 스키마를 관리하려면 다음이 필요합니다: * **Panther API 토큰** * 다음을 참조하세요 [API 토큰을 생성하는 방법에 대한 다음 안내를 따르세요](/ko/panther/api.md#how-to-create-a-panther-api-token)그리고 다음이 있는지 확인하세요 [올바른 권한](/ko/panther/detections-repo/pat/pat-commands.md#permissions-required-per-command) 각 명령에 대해. * 이 API 토큰은 다음에 대한 인수로 전달하게 됩니다. `panther_analysis_tool` 디택션, 사용자 지정 스키마, 저장된 쿼리 등을 업로드/삭제하는 작업에 대한 명령. [사용 예시는 이 섹션을 참조하세요.](#uploading-to-panther) * **Panther API 호스트 이름** * Panther API 호스트 이름은 다음과 같은 형식입니다:\ `https://api..runpanther.net/public/graphql` * **이름 아래의 GitHub 비밀 값으로 추가된 Panther 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 Console에 업로드하는 방법을 설명합니다. GitHub Actions를 사용하는 경우 권장되는 방법입니다. 또한 다음을 통해 Panther Console에 직접 업로드할 수도 있습니다. `panther_analysis_tool`자세한 내용은 다음을 참조하세요 [Panther Analysis Tool](/ko/panther/detections-repo/pat.md). {% endhint %} ## 구성 **Panther용 GitHub Actions** ### 1단계: panther-analysis GitHub 저장소의 Panther 관리 디택션을 사용하기 다음 문서를 따라 panther-analysis GitHub 저장소의 Panther 관리 디택션을 사용하세요: [Panther 디택션 저장소 사용하기](/ko/panther/detections-repo.md). ### 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. 다음을 클릭하세요. **새 워크플로**.\ ![The image shows the Panther-analysis repo in Github. There is a red circle around the "New Workflow" button on the left.](/files/4193bf33460bc7bfcfb838d0ca901d67c20c013e) 4. 다음을 클릭하세요. ***직접 워크플로 설정 →**.*\ ![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."](/files/2fb6376bb3bf2b43ae1d62f96589e9a389a434b5) 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: panther_analysis_tool을 사용하여 탐지 항목에 대한 단위 테스트 실행 steps: - name: 저장소 체크아웃 uses: actions/checkout@a5ac7e51b41094c92402da3b24376905380afc29 #v4.1.6 - name: Python 버전 설정 uses: actions/setup-python@82c7e631bb3cdc910f68e0081d67478d79c6982d #v5.1.0 with: python-version: '3.11' - name: pipenv 설치 run: pip install pipenv - name: Python 종속성 및 panther_analysis_tool 설치 run: make venv - name: 모든 탐지 항목에 대한 단위 테스트 실행 run: pipenv run panther_analysis_tool test panther_analysis_tool_upload: runs-on: ubuntu-latest name: panther_analysis_tool을 사용하여 탐지를 Panther 콘솔에 업로드 needs: [run_unit_tests] env: PANTHER_API_TOKEN: ${{ secrets.API_TOKEN }} PANTHER_API_HOST: "https://api..runpanther.net/public/graphql" steps: - name: 저장소 체크아웃 uses: actions/checkout@a5ac7e51b41094c92402da3b24376905380afc29 #v4.1.6 - name: Python 버전 설정 uses: actions/setup-python@82c7e631bb3cdc910f68e0081d67478d79c6982d #v5.1.0 with: python-version: '3.11' - name: pipenv 설치 run: pip install pipenv - name: Python 종속성 및 panther_analysis_tool 설치 run: make venv - name: 탐지를 Panther 인스턴스에 업로드 # (선택 사항) 아래 명령에 `--filter Enabled=true`를 추가하면 Enabled 탐지만 업로드할 수 있습니다 run: pipenv run panther_analysis_tool upload --skip-tests ``` {% endcode %}
* 다음 환경 변수의 값을 업데이트해야 합니다: * `PANTHER_API_HOST` 의 줄 `39`: 다음으로 바꾸세요 `` 를 Panther 인스턴스의 공용 GraphQL URL로. * 이 워크플로는 Panther API 토큰을 이름으로 GitHub 시크릿에 추가했다고 가정합니다 `API_TOKEN`. 아직 하지 않았다면, 다음의 안내를 따르세요 [사전 요구 사항](#prerequisites). * 이 워크플로를 특정 폴더 내 콘텐츠의 업데이트에만 트리거되도록 하려면, 다음을 추가할 수 있습니다 `paths` 안에 `on.push`. 다음에 대해 자세히 알아보려면 `paths` 의 [GitHub 문서](https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#onpushpull_requestpull_request_targetpathspaths-ignore). 이렇게 하면 생성한 테스트가 탐지 항목에 대해 실행된 다음, 통과하면 모든 Panther 콘텐츠(Lookup Tables, Data Models, 그리고 탐지 항목)가 업로드됩니다. ### 4단계: 변경 사항 푸시 * 실행 `git push`. Github Actions 워크플로가 완료되면, 다음에 `git push` 를 사용하여 `paths` 섹션의 워크플로에서 폴더를 변경할 때 다음이 발생합니다: * 사용자 정의 탐지는 다음으로 테스트됩니다 `panther_analysis_tool`. * 성공하면 탐지 항목이 Panther Console에 업로드됩니다. ## 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) 를 사용할 수 있습니다, 한번 [복제한](/ko/panther/detections-repo/setup/deprecated/private-cloned-repo.md) 또는 [포크한](/ko/panther/detections-repo/setup/deprecated/public-fork.md) 저장소. {% hint style="warning" %} [워크플로](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): 코드가 올바르게 포맷되어 있고 명백한 보안 결함이 없는지 확인합니다. * [Check MITRE ATT\&CK Mapping Format](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`](/ko/panther/detections-repo/pat/pat-commands.md#test-running-unit-tests). * [Validate](https://github.com/panther-labs/panther-analysis/blob/develop/.github/workflows/validate.yml): 사용자 지정 로그 유형과 쿼리에 사용되는 데이터 레이크 테이블 이름의 존재를 확인하는 것을 포함하여 Panther 백엔드와 비교해 콘텐츠를 검증합니다. 다음을 사용합니다. [`panther_analysis_tool validate`](/ko/panther/detections-repo/pat/pat-commands.md#validate-ensuring-detection-content-is-ready-to-be-uploaded). * Validate는 다음 이후에만 실행됩니다. *이후* PR이 승인된 후입니다. 이는 Panther에 대해 오래 걸리는 API 요청을 만들어야 하기 때문에, PR당 여러 번 실행하기에 적합하지 않기 때문입니다. * [Build Docker Image (Deprecated)](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 상위(upstream) 저장소의 가장 최근 변경 사항을 추가하기 위해 저장소에 새 PR을 엽니다. 이 워크플로를 사용하여 복제했거나 포크한 저장소를 Panther가 관리하는 콘텐츠의 업데이트와 동기화하세요. * 이 워크플로는 매주 수요일 15:00 UTC에 실행되며, 수동으로도 트리거할 수 있습니다. * [Upload](https://github.com/panther-labs/panther-analysis/blob/develop/.github/workflows/upload.yml): 다음을 사용하여 저장소의 전체 콘텐츠를 Panther 인스턴스에 업로드합니다. [`panther_analysis_tool upload`](/ko/panther/detections-repo/pat/pat-commands.md#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 paths: - 'schemas/**' jobs: download_pantherlog_tool: runs-on: ubuntu-latest 스키마 테스트에 사용할 pantherlog 도구를 다운로드하는 이름 steps: - name: pantherlog 다운로드 및 압축 해제 run: curl -sSO "https://panther-community-us-east-1.s3.amazonaws.com/latest/tools/linux-amd64-pantherlog.zip" && unzip linux-amd64-pantherlog.zip - name: pantherlog 아티팩트 생성 uses: actions/upload-artifact@65462800fd760344b1a7b4382951275a0abb4808 #v4.3.3 with: name: pantherlog path: pantherlog retention-days: 1 run_schema_tests: runs-on: ubuntu-latest name: pantherlog로 스키마 테스트 실행 needs: [download_pantherlog_tool] steps: - name: 저장소 체크아웃 uses: actions/checkout@a5ac7e51b41094c92402da3b24376905380afc29 #v4.1.6 - name: 아티팩트에서 Pantherlog 도구 다운로드 uses: actions/download-artifact@65a9edc5881444af0b9093a5e628f2fe47ea3b2e #v4.1.7 with: name: pantherlog - name: pantherlog를 실행 가능하게 만들기 run: sudo chmod +x pantherlog - name: pantherlog로 스키마 테스트 수행 run: ./pantherlog test ./schemas run_unit_tests: runs-on: ubuntu-latest name: panther_analysis_tool을 사용하여 탐지 항목에 대한 단위 테스트 실행 steps: - name: 저장소 체크아웃 uses: actions/checkout@a5ac7e51b41094c92402da3b24376905380afc29 #v4.1.6 - name: Python 버전 설정 uses: actions/setup-python@82c7e631bb3cdc910f68e0081d67478d79c6982d #v5.1.0 with: python-version: '3.11' - name: pipenv 설치 run: pip install pipenv - name: Python 종속성 및 panther_analysis_tool 설치 run: make venv - name: 모든 룰 탐지에 대한 단위 테스트 실행 run: pipenv run panther_analysis_tool test --filter AnalysisType=룰 - name: 모든 예약된 룰 탐지에 대한 단위 테스트 실행 run: pipenv run panther_analysis_tool test --filter AnalysisType=scheduled_룰 - name: 모든 정책 탐지에 대한 단위 테스트 실행 run: pipenv run panther_analysis_tool test --filter AnalysisType=policy panther_analysis_tool_upload: runs-on: ubuntu-latest name: panther_analysis_tool을 사용하여 탐지를 Panther 콘솔에 업로드 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: 저장소 체크아웃 uses: actions/checkout@a5ac7e51b41094c92402da3b24376905380afc29 #v4.1.6 - name: Python 버전 설정 uses: actions/setup-python@82c7e631bb3cdc910f68e0081d67478d79c6982d #v5.1.0 with: python-version: '3.11' - name: pipenv 설치 run: pip install pipenv - name: Python 종속성 및 panther_analysis_tool 설치 run: make venv - name: 탐지를 Panther 인스턴스에 업로드 run: pipenv run panther_analysis_tool upload --batch --skip-tests - name: 사용자 지정 스키마를 Panther 인스턴스에 업로드 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` 를 사용하여 `paths` 섹션의 워크플로에서 폴더를 변경할 때 다음이 발생합니다: * 사용자 지정 로그 스키마는 다음으로 테스트됩니다 `pantherlog`. * 사용자 정의 탐지는 다음으로 테스트됩니다 `panther_analysis_tool`. * 성공하면 스키마와 탐지가 Panther Console에 업로드됩니다. ## 선택 사항: Panther에서 GitHub 워크플로 사용자 지정 선택적으로 이 워크플로를 확장하거나 사용자 지정하여 조직에 더 잘 맞게 만들 수 있습니다. 다음은 Panther에서 일반적으로 사용하는 워크플로 사용자 지정입니다: * 다음에 대해 린팅 수행 `.py` 파일 * 특정 폴더에 대한 Push 대신 승인된 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) 가 Panther 탐지를 최신 상태로 유지하는 데 도움이 될 수 있습니다. 태그 기준으로 매주 동기화할 것을 권장합니다. {% 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) 워크플로)가 Dependabot이 연 PR에서는 실패한다는 뜻입니다. 이를 해결하려면 GitHub의 다음을 따르세요 [Dependabot 전용의 별도 리포지토리 비밀 정보를 저장하는 방법](https://docs.github.com/en/code-security/dependabot/working-with-dependabot/configuring-access-to-private-registries-for-dependabot#adding-a-repository-secret-for-dependabot). 이 방법을 사용할 경우 다음을 추가해야 합니다 `API_HOST` 및 `API_TOKEN` 를 비밀 정보로 추가해야 합니다. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.panther.com/ko/panther/detections-repo/ci-cd/deployment-workflows/github-actions.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.