GitHub Actions를 통한 Panther 콘텐츠 관리

GitHub Actions를 사용한 CI/CD 워크플로우로 Panther의 디텍션 및 스키마 관리하기

개요

GitHub Actions를 구성하여 테스트를 자동화하고, 디텍션을 사용자화하며, GitHub 리포지토리에서 Panther 콘솔로 디텍션 파이프라인을 업로드할 수 있습니다. 이 가이드는 다음 항목을 안내합니다:

• GitHub Actions를 통해 사용자 지정 워크플로우 생성

• 사용자 지정 스키마 및 디텍션 테스트

• 스키마 및 디텍션을 Panther 콘솔로 업로드

• 조직의 요구에 맞게 GitHub Actions 워크플로우 사용자화

참조 Panther 콘텐츠용 CI/CD CI/CD 워크플로우를 Panther로 시작하는 방법에 대한 정보.

사전 요구 사항

GitHub Actions를 사용하여 Panther 디텍션 및 스키마를 관리하려면 다음이 필요합니다:

• Panther API 토큰

  • 참조 API 토큰 생성에 대한 이러한 지침및, 해당 토큰에 올바른 권한 이 각 명령에 대해 필요합니다.

  • 이 API 토큰을 다음 panther_analysis_tool 명령의 인수로 전달하여 디텍션 업로드/삭제, 사용자 지정 스키마, 저장된 쿼리 등과 같은 작업을 수행합니다. 사용 예시는 이 섹션을 참조하세요.

• Panther API 호스트 이름

  • Panther API 호스트 이름은 다음과 같이 보입니다: https://api.<your-panther-instance-name>.runpanther.net/public/graphql

• GitHub 시크릿으로 API 토큰을 다음 이름으로 추가 API_TOKEN

  • 토큰을 Secrets에 추가하려면 다음을 따르십시오 GitHub 문서: 리포지토리를 위한 암호화된 시크릿 생성. 이 시크릿은 문서의 이후 부분에서 다음과 같이 표시됩니다 secrets.API_TOKEN.

이 가이드는 Panther API 키와 GitHub 시크릿을 사용하여 GitHub Actions를 통해 Panther 콘솔로 업로드하는 방법을 설명합니다. GitHub Actions를 사용하는 경우 권장되는 방법입니다. 또한 다음을 통해 Panther 콘솔로 직접 업로드할 수도 있습니다 panther_analysis_tool. 자세한 내용은 프로그램 방식으로 업로드할 수 있습니다.

구성 Panther용 GitHub Actions

단계 1: panther-analysis GitHub 리포에서 Panther 관리 디텍션 사용

panther-analysis GitHub 리포의 Panther 관리 디텍션을 사용하려면 문서를 따르십시오: Panther 디텍션 리포 사용.

단계 2: 새로운 GitHub 워크플로우 생성

1. 자동화를 설정하려는 GitHub 리포지토리로 이동합니다.

2. 해당 GitHub 리포지토리 내에서 다음으로 이동합니다 Actions.

3. 를 선택하고 Panther가 설치된 계정 ID를 입력하십시오. 새 워크플로우.

4. 를 선택하고 Panther가 설치된 계정 ID를 입력하십시오. 직접 워크플로우 설정 →.

5. 다음 페이지에서 기본 파일 이름(main.yml)을 설명적인 이름으로 바꿉니다. 예: panther-workflow.yml.

단계 3: 디텍션을 테스트하고 데이터를 업로드하는 워크플로우 구성

• YAML 파일에 다음 코드를 추가하세요:

GitHub 워크플로우 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.<your-panther>.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

• 다음 환경 변수의 값을 업데이트했는지 확인하세요:

  • PANTHER_API_HOST 다음 줄에서 39: 바꿉니다 <your-panther> 를 Panther 인스턴스의 공개 GraphQL URL로 교체하세요.

• 이 워크플로우는 Panther API 토큰을 다음 이름의 GitHub 시크릿으로 추가했다고 가정합니다 API_TOKEN. 아직 추가하지 않았다면 다음의 지침을 따르십시오 사전 요구 사항.

• 이 워크플로우가 특정 폴더 내의 콘텐츠 업데이트에서만 트리거되도록 하려면, 다음을 추가할 수 있습니다 내에서 다음 안에 on.push. 자세한 내용은 내에서 에서 GitHub의 문서.

이 작업은 생성한 디텍션에 대해 테스트를 실행한 다음, 테스트에 합격한 경우 모든 Panther 콘텐츠(조회 테이블, 데이터 모델 및 디텍션)를 업로드합니다.

단계 4: 변경 사항 푸시

• 다음 명령을 실행하세요: git push.

GitHub Actions 워크플로우가 완료된 후, 다음 번에 다음을 사용하여 변경을 수행하면 다음이 발생합니다 git push 워크플로우의 폴더를 변경하기 위해 내에서 섹션:

• 사용자 지정 디텍션은 다음으로 테스트됩니다 panther_analysis_tool.

• 성공하면 디텍션이 Panther 콘솔로 업로드됩니다.

Panther 제공 GitHub 워크플로우

사용자를 사용할 것이며, panther-analysis workflows 디렉터리 에는 여러 개의 즉시 사용 가능한 GitHub 워크플로우 가 포함되어 있으며, 이를 다음을 통해 사용할 수 있습니다 clone 이전에 생성한 Snowflake 사용자 이름, 예를 들면 또는 리포지토리를 fork 한 후.

워크플로우(Workflows) 이름에 "(Internal)"이 포함된(예: "Pre-Release Upload to GA (Internal)"), 워크플로우는 고객용으로 의도된 것이 아닙니다. 자체 리포지토리에서 이를 실행하려고 하면 예기치 않은 결과가 발생할 수 있습니다.

아래 워크플로우는 새 풀 리퀘스트(PR)가 생성될 때 트리거되도록 구성되어 있습니다:

• Lint: 코드가 적절히 포맷되어 있고 명백한 보안 결함이 없는지 확인합니다.

• MITRE ATT&CK 매핑 형식 확인: 디텍션에 포함된 MITRE 매핑의 형식이 유효한지 확인합니다.

• 테스트: 다음을 사용하여 디텍션 및 글로벌 헬퍼에 대한 모든 단위 테스트를 실행합니다 panther_analysis_tool test.

• Validate: 사용자 지정 로그 유형 및 쿼리에 사용되는 데이터 레이크 테이블 이름의 존재 확인을 포함하여 Panther 백엔드에 대해 콘텐츠를 검증합니다. 사용되는 명령: panther_analysis_tool validate.

  • Validate는 이후에만 실행됩니다 PR이 승인된 후입니다. 이는 Panther에 장시간 실행되는 API 요청을 해야 하기 때문에 PR당 여러 번 실행하기에 적합하지 않기 때문입니다.

• Docker 이미지 빌드(더 이상 권장되지 않음): 향후 워크플로우가 실행될 새 도커 컨테이너를 빌드합니다.

다음 워크플로우는 PR 외부에서 트리거됩니다:

• Sync Panther Analysis from Upstream: panther-analysis 업스트림 리포지토리의 최신 변경 사항을 리포지토리에 추가하기 위해 새 PR을 엽니다. 이 워크플로우를 사용하여 클론하거나 포크한 리포지토리를 Panther 관리 콘텐츠의 업데이트와 동기화하세요.

  • 이 워크플로우는 매주 수요일 15:00 UTC에 실행되며 수동으로 트리거할 수도 있습니다.

• 업로드: 리포지토리의 전체 콘텐츠를 다음을 사용하여 Panther 인스턴스로 업로드합니다 panther_analysis_tool upload.

  • 업로드 워크플로우의 트리거는 사용자가 구성해야 합니다. 보통 PR이 main에 병합될 때마다 이 워크플로우가 실행되도록 구성하는 것이 권장되지만, 필요에 따라 다를 수 있습니다.

선택 사항: 사용자 지정 스키마용 워크플로우 빌드

사용자 지정 스키마를 빌드하는 경우, 다음 YAML 코드를 사용하여 워크플로우에 스키마를 포함하세요:

스키마 포함 GitHub 워크플로우 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.<your-panther>.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/

• 다음 환경 변수의 값을 업데이트했는지 확인하세요:

  • PANTHER_API_HOST 다음 줄에서 79: 바꿉니다 <your-panther> 를 Panther 인스턴스의 공개 GraphQL URL로 교체하세요.

• 이 워크플로우는 스키마가 /schemas 디렉터리에 저장되어 있다고 가정합니다. 다른 위치에 저장되어 있다면, 다음 줄에서 위치를 업데이트하세요 11 , 44및 99.

• 이 워크플로우는 Panther API 토큰을 다음 이름의 GitHub 시크릿으로 추가했다고 가정합니다 API_TOKEN. 아직 추가하지 않았다면 다음의 지침을 따르십시오 사전 요구 사항.

변경 사항 푸시

• 다음 명령을 실행하세요: git push.

이제 다음 번에 다음을 사용하여 변경을 수행하면 다음이 발생합니다 git push 워크플로우의 폴더를 변경하기 위해 내에서 섹션:

• 사용자 지정 로그 스키마는 다음으로 테스트됩니다 pantherlog.

• 사용자 지정 디텍션은 다음으로 테스트됩니다 panther_analysis_tool.

• 성공하면 스키마와 디텍션이 Panther 콘솔로 업로드됩니다.

선택 사항: Panther에서 GitHub 워크플로우 사용자화

선택적으로 이 워크플로우를 확장하거나 사용자화하여 조직에 더 적합하게 만들 수 있습니다. 다음은 Panther와 함께 자주 사용하는 워크플로우 사용자화 예시입니다:

• 다음에 대해 린팅 수행 .py 파일

• 특정 폴더로의 푸시 대신 승인된 PR에서 트리거되도록 설정.

• 다음을 포크한 경우 panther-analysis 최신 태그로 리포지토리를 포크하는 방법에 대해 알아보려면, 다음을 확인하세요 포크 동기화 태그별로 주간 동기화를 권장합니다.

GitHub 워크플로우에 대한 자세한 내용은 다음을 참조하세요 GitHub의 문서.

선택 사항: Dependabot 사용

Dependabot 은 GitHub에서 일반적으로 사용되는 통합으로 리포지토리의 종속성에 대해 보안 위험 및 사용 가능한 업데이트를 지속적으로 점검합니다. Panther는 업스트림 런타임 환경(예: panther-analysis)을 관리하지만, 추가 보안 계층으로 Dependabot을 사용할 수 있습니다. Panther 리포지토리에 대해 Dependabot을 설정하려면 GitHub의 Dependabot 빠른 시작 가이드.

를 따르십시오. Dependabot은 종속성을 업데이트하기 위해 PR을 열 수 있습니다. 그러나 Dependabot은 리포지토리의 시크릿에 접근할 수 없습니다. 이는 API 시크릿이 필요한 GitHub 워크플로우(예: test

워크플로우)가 Dependabot이 연 PR에서는 실패함을 의미합니다. 이를 해결하려면 GitHub의 다음 지침을 따르십시오특히 Dependabot을 위해 별도의 리포지토리 시크릿 세트를 저장하는 방법 . 이 방법을 사용할 경우, 다음을 추가해야 합니다 와 API_TOKEN API_HOST