> For the complete documentation index, see [llms.txt](https://docs.panther.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.panther.com/ko/panther/detections-repo/github-app.md). # Panther GitHub App 설정(베타) {% hint style="warning" %} Panther GitHub App은 Panther 버전 1.125부터 오픈 베타입니다. 버그 신고와 기능 요청은 Panther 지원 팀에 공유해 주세요. {% endhint %} ## 개요 디택션 콘텐츠 저장소에 Panther GitHub App을 설치하면 Panther가 대신 저장소에서 pull request를 열 수 있습니다. 앱이 설치되면 Panther Console에서 지원되는 디택션 유형을 편집할 때 Panther에 직접 저장하는 대신 저장소에 pull request가 생성됩니다— [Panther Console에서 GitHub 풀 리퀘스트 만들기](/ko/panther/overview.md#creating-a-github-pull-request-from-the-panther-console) 지원되는 유형 목록은 여기를 참조하세요. 설정 과정에는 **두 역할이**포함되며, 두 명이 맡을 수도 있고 한 사람이 둘 다 맡을 수도 있습니다: * 한 **Panther 사용자** 그 역할로 `설정 및 SAML 기본 설정 편집` 권한이 있는 사람으로, Panther Console에서 git 저장소를 구성하고 등록 링크를 생성합니다. * 한 **GitHub 조직 소유자**등록 링크를 열고 GitHub에서 앱 등록 및 설치를 완료합니다. 이 사람은 **않습니다** Panther 계정이 필요하지 않습니다. Panther 사용자가 링크를 생성하고 대상 저장소 이름과 함께 GitHub 조직 소유자에게 공유합니다(이메일, Slack 또는 기타 채널을 통해). 링크는 **24시간** 유효하며 한 번만 사용할 수 있습니다. 새 링크를 생성하면 이전 링크는 무효화됩니다. ## 사전 요구 사항 * 모든 Panther 디택션 콘텐츠는 하나의 **단일** GitHub 저장소에 있습니다. 현재 Panther GitHub App은 여러 저장소와의 통합을 지원하지 않습니다. * 등록 링크를 여는 사람은 **소유자** 여러분의 디택션 저장소가 포함된 GitHub 조직의 소유자여야 합니다. GitHub은 소유자가 아닌 사람이 조직을 대신해 앱을 등록하는 것을 허용하지 않습니다. ## 1단계: 저장소를 구성하고 등록 링크 생성(Panther 사용자) {% hint style="warning" %} 저장소 구성을 저장하면 Panther Console이 지원되는 디택션 유형 편집을 처리하는 방식이 즉시 변경됩니다. 즉, Panther에 직접 저장하는 대신 Console이 여러분의 저장소에 대해 pull request를 엽니다([Create PR](/ko/panther/overview.md#creating-a-github-pull-request-from-the-panther-console) 모드). Panther GitHub App이 설치되어 해당 저장소에 연결될 때까지 Create PR은 실패하므로 해당 디택션 유형에 대한 Console 편집은 차단됩니다. 팀이 이러한 동작 변경에 준비되었을 때만 구성을 저장하세요. {% endhint %} 1. Panther Console에서 오른쪽 상단의 톱니바퀴 아이콘을 클릭하여 설정을 연 다음 **개발자 도구** > **Git 동기화**. 2. 에서 **Git 동기화** 섹션으로 이동하여 다음 필드를 채우세요: * **GitHub 조직**: 디택션 저장소를 소유한 GitHub 조직의 이름. * **저장소 이름**: Panther 디택션 콘텐츠가 들어 있는 저장소의 이름. * **브랜치 이름**: Panther가 제출해야 하는 브랜치 [pull request](/ko/panther/overview.md#creating-a-github-pull-request-from-the-panther-console) 를 Console에서 발생한 변경 사항에 대해 제출합니다—일반적으로 `main` 또는 `master`. 3. 클릭하세요 **저장소 저장**. **GitHub App 등록** 섹션이 아래에 표시되며 **연결 편집** 및 **연결 끊기** 버튼이 구성 필드 옆에 표시됩니다. 이 버튼은 언제든지 사용할 수 있습니다— [통합 수정 또는 제거](#editing-or-removing-the-integration) 에서 각 버튼의 효과를 확인하세요.
The Git Sync section with a saved repository configuration and a GitHub App Registration section below it containing a Generate Registration Link button.

다음을 클릭하기 전에 등록 링크 생성 을 다음 단계에서 클릭하기 전에, GitHub 조직 소유자가 24시간 이내에 GitHub에서 등록을 완료할 수 있는지 확인하세요. 생성된 링크는 그 기간 동안만 유효합니다.

4. 클릭하세요 **등록 링크 생성**. Panther는 전체 URL을 **등록 링크** 필드.
The GitHub App Registration section with a generated Registration Link URL displayed below the Generate Registration Link button.
5. 클릭하세요 **복사** 에 표시하며, GitHub 조직 소유자에게 다음 두 가지 정보를 공유하세요: * 등록 링크. * 대상 저장소 이름( **저장소 이름** 위 필드에서 가져온 값)입니다. 그래야 앱을 설치할 때 올바르게 선택할 수 있습니다. {% hint style="info" %} 등록 링크는 다음 경우마다 무효화됩니다: **모든** 다음 권한을 가진 Panther 사용자가 `설정 및 SAML 기본 설정 편집` 클릭하면 **등록 링크 생성**—Panther Console을 열어 독립적으로 링크를 생성한 다른 사용자도 포함됩니다. 공유한 링크가 작동하지 않으면 팀의 다른 누군가가 새 링크를 생성했는지 확인하고, 현재 링크를 저장소 이름과 함께 다시 공유하세요. {% endhint %} ## 2단계: 등록 링크 열기(GitHub 조직 소유자) GitHub 조직 소유자가 브라우저에서 링크를 엽니다. Panther 계정은 필요하지 않습니다.
The Panther public registration page, titled 'Register the Panther GitHub App,' showing the target GitHub organization and expiry time, with a Continue to GitHub button.
페이지에는 앱이 등록될 GitHub 조직과 링크 만료 시간이 표시됩니다. GitHub 조직 소유자가 **GitHub로 계속**. 등록 정보 대신 오류가 표시되면 다음을 참조하세요: [링크를 처음 열 때 오류가 표시됨](#an-error-appears-when-first-opening-the-link). ## 3단계: GitHub에서 GitHub App 만들기 GitHub에는 미리 채워진 앱 이름이 있는 양식이 표시됩니다(예: `{your-org}-panther-gh-app`). GitHub 조직 소유자는 원하는 경우 이름을 변경할 수 있지만, GitHub 전체에서 고유해야 합니다.
GitHub's Create GitHub App page with a pre-filled GitHub App name field and a Create GitHub App button.
GitHub 조직 소유자가 **GitHub App 만들기**. 등록이 성공하면 GitHub가 앱 설치 페이지로 이동시킵니다. 그렇지 않으면 브라우저는 오류 페이지로 이동합니다. GitHub 자체 오류이거나, 오류 메시지가 있는 Panther 등록 페이지입니다: * GitHub이 앱 이름을 거부하면 다음을 참조하세요: [앱 이름이 이미 GitHub에서 사용 중입니다](#the-app-name-is-already-taken-on-github). * 브라우저가 오류와 함께 Panther 등록 페이지로 다시 리디렉션되면 다음을 참조하세요: [Create GitHub App 또는 Install을 클릭한 후 오류가 표시됨](#an-error-appears-after-clicking-create-github-app-or-install). ## 4단계: 대상 저장소에 앱 설치 GitHub의 설치 페이지에서 GitHub 조직 소유자가 **선택한 저장소만**를 선택한 다음 대상 저장소(1단계에서 Panther 사용자가 공유한 저장소)를 선택하고 **설치**.
GitHub's app installation page with 'Only select repositories' selected and one repository chosen.
{% hint style="warning" %} 앱은 대상 저장소에만 설치하세요. 다른 저장소 조합에 설치하면 Panther Console에서 경고 또는 오류가 발생합니다— [앱은 설치되었지만 Panther가 대상 저장소에 액세스할 수 없습니다](#the-app-was-installed-but-panther-cant-access-the-target-repository) 및 [앱이 대상 저장소를 포함한 여러 저장소에 설치되었습니다](#the-app-was-installed-on-multiple-repositories-including-the-target). {% endhint %} 설치가 성공하면 GitHub가 브라우저를 Panther Console로 다시 리디렉션합니다. GitHub 조직 소유자가 Panther에 로그인되어 있지 않다면(일반적인 경우), Panther 로그인 페이지로 이동합니다. 탭을 닫아도 됩니다. 여기서 역할은 끝납니다. 오류가 발생하면 브라우저가 오류 메시지와 함께 Panther 등록 페이지로 다시 리디렉션됩니다— [Create GitHub App 또는 Install을 클릭한 후 오류가 표시됨](#an-error-appears-after-clicking-create-github-app-or-install). ## 5단계: Panther Console에서 결과 검토(Panther 사용자) Panther는 구성된 저장소에 대해 연결 테스트를 자동으로 실행하고 Panther Console에 알림을 전달합니다. 다음 권한이 있는 Panther 사용자는 `설정 및 SAML 기본 설정 편집` 이 알림을 받으며, 수신 거부할 수 없습니다. 설치가 성공했고 앱이 대상 저장소에 액세스할 수 있으면 Panther 사용자는 성공 알림을 받습니다:
The Panther Notifications panel showing a 'GitHub App Installed Successfully' notification confirming the connection to the configured repository.
연결은 다음에서도 확인할 수 있습니다: **설정** > **개발자 도구** > **Git 동기화**. **동기화 상태** 섹션에는 가장 최근 테스트 결과가 표시되며 **구성 테스트** 섹션에는 저장소에 접근 가능한지와 구성된 브랜치가 존재하는지가 표시됩니다. 언제든지 다음을 클릭하여 테스트를 다시 실행할 수 있습니다: **연결 테스트** 에서 **구성 테스트** 섹션:
The Developer Workflow tab in Panther Settings showing a successful Test Configuration with green checkmarks next to 'Repository accessible' and 'Branch main exists'.
성공 알림이 표시되면 git 통합이 완전히 구성된 것입니다. 이제 [Panther Console에서 pull request를 생성할 수 있습니다](/ko/panther/overview.md#creating-a-github-pull-request-from-the-panther-console) 디택션을 편집하거나 생성할 때 가능합니다. 대신 경고 또는 오류 알림이 표시되면 다음을 참조하세요: * **경고**: [앱이 대상 저장소를 포함한 여러 저장소에 설치되었습니다](#the-app-was-installed-on-multiple-repositories-including-the-target). * **오류**: [앱은 설치되었지만 Panther가 대상 저장소에 액세스할 수 없습니다](#the-app-was-installed-but-panther-cant-access-the-target-repository). ## 통합 수정 또는 제거 Panther 사용자는 저장소 구성을 편집하거나 통합을 완전히 제거할 수 있습니다. **Git 동기화** 섹션의 **설정** > **개발자 도구** > **Git 동기화**다음에서 가능합니다. 두 옵션은 구성이 처음 저장된 이후 언제든지 사용할 수 있으며, 등록 흐름이 진행 중일 때도 가능합니다. * **연결 편집** 다음을 열면 **GitHub 조직**, **저장소 이름**, 그리고 **브랜치 이름** 편집용 필드가 표시됩니다. 구성을 편집해도 현재 진행 중인 등록 흐름에는 영향을 주지 않습니다. * **연결 끊기** 이 깔끔한 제거 경로입니다. 다음을 클릭하면 **연결 끊기** 저장소 구성이 완전히 제거되고 Panther GitHub App이 저장소에서 제거됩니다. 이로 인해 진행 중인 등록 링크도 무효화되며, Panther Console은 기본 디택션 저장 동작으로 돌아갑니다(Create PR을 통해 편집을 라우팅하지 않음). GitHub의 기존 pull request에는 영향을 주지 않으며, 계속 열려 있습니다. 연결을 끊은 후 통합을 다시 설정하려면 다음에서 다시 시작하세요: [1단계](#step-1-configure-the-repository-and-generate-a-registration-link-panther-user). ## 문제 해결 ### 링크를 처음 열 때 오류가 표시됨 GitHub 조직 소유자가 등록 링크를 열었는데 등록 정보 대신 즉시 오류가 표시되면:
The Panther public registration page showing a 'Registration Link Invalid' error message: 'This registration link is invalid or has expired. Please contact your Panther administrator for a new link.'
가장 가능성이 높은 원인은 다음과 같습니다: * **링크가 잘못 복사되었습니다.** URL이 잘리거나 손상되는 채널(예: 줄바꿈되어 전송되는 채팅 클라이언트)로 링크를 공유했다면, Panther Console에서 링크를 다시 복사하여 재공유하세요. * **링크가 만료되었습니다.** 등록 링크는 생성된 시점부터 24시간 동안 유효합니다. 복구하려면 Panther 사용자가 다음으로 돌아가 [1단계](#step-1-configure-the-repository-and-generate-a-registration-link-panther-user) 새 등록 링크를 생성한 다음, 저장소 이름과 함께 GitHub 조직 소유자에게 공유합니다. 그런 다음 GitHub 조직 소유자가 다음에서 흐름을 다시 시작합니다: [2단계](#step-2-open-the-registration-link-github-organization-owner). ### Create GitHub App 또는 Install을 클릭한 후 오류가 표시됨 GitHub 조직 소유자가 등록 페이지를 성공적으로 불러오고, GitHub로 이동한 뒤 다음 중 하나를 완료했는데도 **GitHub App 만들기** 또는 **설치**이지만, 이후 오류 메시지와 함께 Panther 등록 페이지로 다시 리디렉션되면:
The Panther public registration page showing a 'Registration Link Invalid' error: 'registration flow is no longer valid. Please check your GitHub organization settings for a registered app — if one was created, delete it before retrying with a new registration link.'
가장 가능성이 높은 원인은 다음과 같습니다: * **흐름 진행 중 링크가 만료되었습니다.** GitHub 단계 완료에 24시간 이상이 걸려 서버 측 만료 검사가 실패했습니다. * **링크가 새 링크로 대체되었습니다.** 흐름이 진행 중인 동안 Panther 사용자가 새 등록 링크를 생성했습니다. 새 링크를 생성하면 현재 사용 중인 링크를 포함한 이전 링크는 모두 무효화됩니다. * **Panther 측에서 유효성 검사 오류가 발생했습니다** GitHub와 자격 증명을 교환하는 동안. 오류가 발생하기 전에 흐름이 어느 정도 진행되었는지에 따라, 이 시점에서 GitHub 조직에 GitHub App이 이미 존재할 수도 있습니다. 복구하려면: 1. GitHub 조직 소유자가 브라우저에서 GitHub 조직을 열고 **설정**를 클릭한 다음 왼쪽 사이드바에서 **개발자 설정** 을 펼치고 **GitHub Apps**:
The GitHub organization settings page with the left sidebar expanded to show Developer settings, with GitHub Apps highlighted.
페이지에는 조직에 등록된 GitHub Apps가 표시됩니다. 부분적으로 등록된 Panther 앱이 있으면 다음을 클릭하세요: **Edit** 해당 행에서:
The GitHub Apps page in GitHub organization Developer settings, listing GitHub Apps registered to the organization, each with an Edit button.
앱 설정에서 **고급** 탭을 열고 **위험 구역** 섹션으로 스크롤한 다음 **GitHub App 삭제**:
A GitHub App's Advanced settings page showing a 'Danger zone' section with Transfer ownership, Delete this GitHub App, and Make this GitHub App public options.
확인 대화상자를 주의 깊게 읽은 다음 확인 필드에 GitHub App 이름을 입력하세요:
A 'Delete GitHub App?' confirmation dialog warning that the action cannot be undone, with a field to type the app name to confirm.
이름이 일치하면 **결과를 이해했습니다. 이 GitHub App 삭제** 버튼이 활성화됩니다. 이를 클릭하여 앱을 삭제하세요:
The 'Delete GitHub App?' dialog with the confirmation field filled in and the red 'I understand the consequences, delete this GitHub App' button active.
2. Panther 사용자가 다음으로 돌아가 [1단계](#step-1-configure-the-repository-and-generate-a-registration-link-panther-user) 새 등록 링크를 생성한 다음 저장소 이름과 함께 GitHub 조직 소유자에게 공유합니다. 3. GitHub 조직 소유자가 다음에서 흐름을 다시 시작합니다: [2단계](#step-2-open-the-registration-link-github-organization-owner). ### GitHub 조직 소유자가 실제로는 조직 소유자가 아닙니다 GitHub은 앱 등록을 완료하는 사람이 **소유자** 대상 조직의 소유자일 것을 요구합니다. 링크를 여는 사람이 구성원일 뿐 소유자가 아니면, GitHub은 다음 페이지 상단에 배너를 표시합니다: **GitHub App 만들기** 3단계의 페이지에서 권한이 없다고 설명합니다:
GitHub's Create GitHub App page with a banner reading 'You don't have permission to create apps for this organization. Please confirm you have appropriate permissions for this account and have entered the name correctly.'
복구하려면 GitHub 조직 소유자가 등록 링크를 열도록 하세요. 원래 링크가 아직 24시간 유효 기간 내라면 다시 사용할 수 있으며, 새 링크를 생성할 필요가 없습니다. ### 앱 이름이 이미 GitHub에서 사용 중입니다 GitHub App 이름은 GitHub 전체에서 고유해야 합니다. 미리 채워진 이름이 이미 사용 중이면 **GitHub App 만들기** 3단계에서 클릭하면 다음 필드에 '이름이 이미 사용 중입니다' 오류 툴팁이 표시됩니다: **GitHub App 이름** 필드:
GitHub's Create GitHub App page with a 'Name is already taken' error tooltip pointing at the GitHub App name field.
복구하려면 GitHub 조직 소유자가 **GitHub App 이름** 필드를 고유한 값으로 수정한 다음 **GitHub App 만들기** 다시 클릭하세요. 나머지 흐름에는 영향을 주지 않습니다. ### 앱은 설치되었지만 Panther가 대상 저장소에 액세스할 수 없습니다 이는 다음 두 가지 경우에 발생합니다: * 앱이 다음에 설치되었습니다: **단일 저장소** 대상 저장소가 아닌 저장소입니다. Panther 사용자는 다음 오류 알림을 받습니다:
The Panther Notifications panel showing a 'GitHub App Connection Failed' error notification stating that the app was installed but does not have access to the configured repository, with advice to update the app installation.
* 앱이 다음에 설치되었습니다: **여러 저장소**인데, 그중 어느 것도 대상 저장소가 아닙니다. Panther 사용자는 다음 오류 알림을 받습니다:
The Panther Notifications panel showing a 'GitHub App Connection Failed' error notification stating that the app was installed but does not have access to the configured repository, and that the app has access to other repositories it doesn't need, with advice to update the installation to include the configured repository and restrict access to only that repository.
두 경우 모두 설치가 업데이트될 때까지 통합은 작동하지 않습니다. 복구하려면 다음의 단계를 따르세요: [GitHub에서 앱의 저장소 액세스 업데이트](#updating-the-apps-repository-access-on-github) 에서 대상 저장소를 앱이 액세스할 수 있는 유일한 저장소로 설정하세요. Panther 사용자는 다음으로 돌아가 수정이 적용되었는지 확인할 수 있습니다: **설정** > **개발자 도구** > **Git 동기화** 및 다음을 클릭하여 **연결 테스트** 아래의 **구성 테스트** 섹션에서 클릭합니다. 테스트가 성공하면 섹션에 다음 항목 옆에 녹색 체크 표시가 나타납니다: **저장소에 액세스 가능** 및 **브랜치 \[name] 존재**:
The Developer Workflow tab in Panther Settings showing a successful Test Configuration with green checkmarks next to 'Repository accessible' and 'Branch main exists'.
### 앱이 대상 저장소를 포함한 여러 저장소에 설치되었습니다 앱이 여러 저장소에 설치되어 있고 *및* 그중 대상 저장소가 포함되어 있으면 통합은 작동하지만, 앱이 Panther에 필요한 것보다 더 많은 액세스를 갖게 됩니다. Panther 사용자는 액세스를 디택션 저장소로만 제한하라는 경고 알림을 받습니다:
The Panther Notifications panel showing a warning notification: 'GitHub App Installed Successfully. The GitHub App has been installed and connected to the configured repository. However, the app has access to additional repositories. For security best practices, please ask your GitHub admin to restrict the installation to only the configured repository.'
최소 권한 원칙을 따르려면 GitHub 조직 소유자가 다음의 단계를 따라 설치를 제한할 수 있습니다: [GitHub에서 앱의 저장소 액세스 업데이트](#updating-the-apps-repository-access-on-github). 이 시나리오에서는 연결 테스트가 이미 통과하므로 Panther는 변경을 디택션할 수 없습니다. Panther 사용자는 관련 없는 저장소가 제거되었는지 GitHub 조직 소유자에게 직접 확인해야 합니다. ### GitHub에서 앱의 저장소 액세스 업데이트 GitHub 조직 소유자는 등록 흐름을 다시 거치지 않고도 Panther GitHub App이 액세스할 수 있는 저장소를 언제든지 업데이트할 수 있습니다. 다음 단계를 사용하여 설치에 대상 저장소를 추가하거나, 앱이 액세스해서는 안 되는 저장소를 제거하거나, 둘 다 수행하세요. 1. 브라우저에서 GitHub 조직을 열고 **설정**를 클릭한 다음 왼쪽 사이드바의 **타사 액세스** 에서 **GitHub Apps**:
The GitHub organization settings page with the left sidebar Third-party Access section visible and GitHub Apps highlighted.
2. 다음 **설치된 GitHub Apps** 페이지에서 Panther 앱을 찾아 **구성**:
The Installed GitHub Apps page in GitHub organization settings, listing the Panther GitHub App with a Configure button.
3. 다음으로 스크롤하세요: **저장소 액세스** 섹션. 다음이 선택된 상태에서 **선택한 저장소만** 저장소 선택기를 클릭하여 저장소를 추가하거나 제거하세요:
The GitHub App configuration page showing the Repository access section with 'Only select repositories' selected and a search dropdown open for choosing repositories.
4. 선택을 조정하여 대상 저장소가 포함되고 관련 없는 저장소가 제거되도록 하세요. 다음을 클릭하세요: **저장**:
The GitHub App configuration page with 'Only select repositories' selected and a single target repository listed under 'Selected 1 repository,' with Save and Cancel buttons visible.
--- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## 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, and the optional `goal` query parameter: ``` GET https://docs.panther.com/ko/panther/detections-repo/github-app.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.