GitHub Actions를 통한 Panther 콘텐츠 관리

GitHub Actions를 사용한 CI/CD 워크플로로 Panther에서 디텍션과 스키마를 관리합니다

개요

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

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

• 사용자 지정 스키마와 디택션 테스트

• 스키마와 디택션을 Panther Console에 업로드

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

참고 Panther Content용 CI/CD Panther에서 CI/CD 워크플로를 시작하는 방법에 대한 정보는

사전 요구 사항

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 시크릿에 추가된 Panther API 토큰 API_TOKEN

  • 토큰을 Secrets에 추가하려면 다음을 따르세요 GitHub 문서: 저장소용 암호화된 시크릿 만들기. 이 시크릿은 이 문서에서 나중에 다음으로 표시됩니다 secrets.API_TOKEN.

이 가이드는 Panther API 키와 GitHub 시크릿을 사용하여 GitHub Actions를 통해 Panther Console에 업로드하는 방법을 설명합니다. GitHub Actions를 사용 중이라면 권장되는 방법입니다. 또한 다음을 통해 Panther Console로 직접 업로드할 수도 있습니다 panther_analysis_tool. 자세한 내용은 다음을 참조하세요 Panther Analysis Tool.

구성하세요 Panther용 GitHub Actions

1단계: panther-analysis GitHub 저장소의 Panther 관리 디택션 사용

다음 문서를 따라 panther-analysis GitHub 저장소에서 Panther 관리 디택션을 사용하세요: Panther 디택션 저장소 사용.

2단계: 새 GitHub 워크플로 만들기

1. 자동화를 설정할 GitHub 저장소로 이동합니다.

2. GitHub 저장소에서 다음으로 이동합니다 Actions.

3. 다음을 클릭합니다 새 워크플로.

4. 다음을 클릭합니다 직접 워크플로 설정 →.

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

3단계: 디택션 테스트 및 데이터 업로드용 워크플로 구축

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

GitHub 워크플로 YAML

name: Panther Analysis CI/CD 워크플로

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.<your-panther>.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 인스턴스에 디택션 업로드
        # (선택 사항) Enabled 디택션만 업로드하려면 아래 명령에 `--filter Enabled=true`를 추가하세요
        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 콘텐츠(디택션, 데이터 모델, 보강, 예약 프롬프트 등)가 업로드됩니다.

리포지토리에 다음이 포함되어 있다면 예약 프롬프트, API_TOKEN 이 워크플로에서 사용되는 ManageScheduledPrompts 권한(그리고 AIRunAsModify 어떤 프롬프트의 RunAsUser 가 토큰과 다른 경우). 예약 프롬프트에는 API 토큰 인증이 필요하며, 이 워크플로는 이미 이를 사용합니다.

4단계: 변경 사항 푸시

• 실행하세요 git push.

Github Actions 워크플로가 완료되면, 다음에 git push 다음 워크플로의 폴더를 수정할 때 경로 섹션에서 다음이 발생합니다:

• 사용자 지정 디택션은 panther_analysis_tool.

• 성공하면 디택션이 Panther Console에 업로드됩니다.

Panther에서 제공하는 GitHub 워크플로

다음 panther-analysis workflows 디렉터리 에는 바로 사용할 수 있는 여러 개의 GitHub 워크플로 가 들어 있으며, 다음을 한 후 사용할 수 있습니다 클론 또는 포크 리포지토리를.

워크플로 "(Internal)"을 포함한 이름의 항목(예: "GA (Internal)로의 사전 릴리스 업로드")은 고객 사용을 위한 것이 아닙니다. 자신의 리포지토리에서 이를 실행하려고 하면 예상치 못한 결과가 발생할 수 있습니다.

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

• Lint: 코드 형식이 올바르고 명백한 보안 결함이 없는지 확인합니다.

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

• 테스트: 다음을 사용하여 디택션과 전역 헬퍼에 대한 모든 단위 테스트를 실행합니다 panther_analysis_tool test.

• 검증: 사용자 지정 로그 유형과 데이터 레이크 테이블 이름(쿼리에서 사용됨)의 존재 여부 확인을 포함하여 Panther 백엔드에 대해 콘텐츠를 검증합니다. 다음을 사용합니다 panther_analysis_tool validate.

  • Validate는 다음에만 실행됩니다 다음에 PR가 승인된 후입니다. 이는 Panther에 장시간 실행되는 API 요청을 보내야 하므로, PR마다 여러 번 실행하기에는 적합하지 않기 때문입니다.

• Docker 이미지 빌드(사용 중단됨): 향후 워크플로가 실행될 새 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 워크플로

permissions:
  contents: read

on:  
  push:
    branches:
      - main
    paths:
      - 'schemas/**'

jobs: 
  download_pantherlog_tool:
    runs-on: ubuntu-latest
    name: 스키마 테스트에 사용할 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.<your-panther>.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/

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

  • 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 Console에 업로드됩니다.

선택 사항: Panther에서 GitHub 워크플로 사용자 지정

선택적으로, 조직에 더 잘 맞도록 이 워크플로를 확장하거나 사용자 지정할 수 있습니다. Panther에서 흔히 하는 워크플로 사용자 지정은 다음과 같습니다:

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

• 특정 폴더로의 Push 대신 승인된 PR에서 트리거.

• 최신 태그로 저장소를 포크했다면, 다음 방법을 알아보세요 panther-analysis fork 동기화 는 Panther 디택션을 최신 상태로 유지하는 데 도움이 될 수 있습니다. 태그별로 매주 동기화하는 것을 권장합니다. GitHub 워크플로에 대한 자세한 내용은 다음을 참조하세요

선택 사항: Dependabot 사용 GitHub 문서.

Dependabot

Dependabot 는 보안 위험과 사용 가능한 업데이트를 위해 저장소의 종속 항목을 지속적으로 감사하는 GitHub에서 널리 사용되는 통합입니다. Panther는 상위 런타임 환경(즉, panther-analysis)을 관리하지만, 추가 보안 계층으로 Dependabot을 사용할 수 있습니다. Panther 저장소에서 Dependabot을 설정하려면 GitHub의 다음 안내를 따르세요 Dependabot 빠른 시작 가이드.

Dependabot은 종속 항목을 업데이트하는 PR을 열 수 있습니다. 그러나 Dependabot은 저장소의 시크릿에는 접근할 수 없습니다. 이는 API 시크릿이 필요한 GitHub 워크플로(예: 테스트 워크플로)는 Dependabot이 연 PR에서 실패한다는 것을 의미합니다.

이를 해결하려면 GitHub의 다음을 따르세요 Dependabot 전용으로 별도의 저장소 시크릿 집합을 저장하는 방법. 이 방법을 사용하면 다음을 추가해야 합니다 API_HOST 및 API_TOKEN 를 시크릿으로.