> 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 앱(베타) 설정 {% hint style="warning" %} Panther GitHub App은 Panther 버전 1.125부터 오픈 베타입니다. 버그 보고와 기능 요청은 Panther 지원팀에 공유해 주세요. {% endhint %} ## 개요 Panther GitHub App을 디택션 콘텐츠 저장소에 설치하면 Panther가 귀하를 대신해 저장소에 풀 리퀘스트를 열 수 있습니다. 앱이 설치되면, Panther Console에서 지원되는 디택션 유형을 편집할 때 Panther에 직접 저장하는 대신 저장소에 풀 리퀘스트가 생성됩니다—참조 [Panther Console에서 GitHub 풀 리퀘스트 만들기](/ko/panther/overview.md#creating-a-github-pull-request-from-the-panther-console) 지원되는 유형 목록은 설정 과정에는 **두 가지 역할**이 있으며, 두 사람에게 나뉘어 맡겨질 수도 있고 한 사람이 모두 맡을 수도 있습니다: * A **Panther 사용자** 을(를) 다음으로 `설정 및 SAML 환경설정 편집` 권한을 가진 사람으로, Panther Console에서 git 저장소를 구성하고 등록 링크를 생성합니다. * A **GitHub 조직 소유자**등록 링크를 열고 GitHub에서 앱 등록과 설치를 완료하는 사람입니다. 이 사람은 **아닌** Panther 계정이 필요하지 않습니다. Panther 사용자가 링크를 생성해 대상 저장소 이름과 함께 GitHub 조직 소유자에게(이메일, Slack 또는 기타 채널로) 공유합니다. 링크는 **24시간 동안** 유효하며 한 번만 사용할 수 있습니다. 새 링크를 생성하면 이전 링크는 무효화됩니다. ## 사전 요구 사항 * Panther 디택션 콘텐츠는 모두 **하나의** GitHub 저장소에 있습니다. 현재 Panther GitHub App은 여러 저장소와의 통합을 지원하지 않습니다. * 등록 링크를 여는 사람은 귀하의 디택션 저장소가 있는 GitHub 조직의 **owner** 여야 합니다. GitHub는 소유자가 아닌 사람이 조직을 대신해 앱을 등록하는 것을 허용하지 않습니다. ## 1단계: 저장소 구성 및 등록 링크 생성(Panther 사용자) {% hint style="warning" %} 저장소 구성을 저장하면 지원되는 디택션 유형에 대한 Panther Console의 처리 방식이 즉시 바뀝니다. 이제 Console은 Panther에 직접 저장하는 대신 저장소에 대한 풀 리퀘스트를 엽니다([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가 제출할 [풀 리퀘스트](/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에서 풀 리퀘스트를 만들 수 있습니다](/ko/panther/overview.md#creating-a-github-pull-request-from-the-panther-console) 디택션을 편집하거나 생성할 때. 대신 알림이 경고나 오류라면 다음을 참조하세요: * **경고**: [앱이 대상 저장소를 포함한 여러 저장소에 설치되었습니다](#the-app-was-installed-on-multiple-repositories-including-the-target). * **Error**: [앱은 설치되었지만 Panther가 대상 저장소에 액세스할 수 없습니다](#the-app-was-installed-but-panther-cant-access-the-target-repository). ## 통합 편집 또는 제거 Panther 사용자는 저장소 구성을 편집하거나 통합을 완전히 제거할 수 있습니다. **Git 동기화** 의 섹션에서 **설정** > **개발자 도구** > **Git 동기화**. 이 두 옵션은 구성을 처음 저장한 뒤 언제든지 사용할 수 있습니다. 등록 흐름이 진행 중일 때도 마찬가지입니다. * **연결 편집** 다음을 엽니다 **GitHub 조직**, **저장소 이름**, 및 **브랜치 이름** 편집할 필드. 구성을 편집해도 현재 진행 중인 등록 흐름에는 영향이 없습니다. * **연결 해제** 깔끔한 제거 경로입니다. 다음을 클릭하면 **연결 해제** 저장소 구성을 완전히 제거하고 Panther GitHub App을 저장소에서 제거합니다. 또한 진행 중인 등록 링크를 무효화하고, Panther Console을 기본 디택션 저장 동작으로 되돌립니다(Create PR를 통해 편집을 라우팅하지 않음). GitHub의 기존 풀 리퀘스트는 영향을 받지 않으며 계속 열려 있습니다. 연결 해제 후 통합을 다시 설정하려면 [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 앱이 있으면 다음을 클릭합니다 **편집** 해당 행에서:
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는 앱 등록을 완료하는 사람이 **owner** 대상 조직의 여야 한다고 요구합니다. 링크를 여는 사람이 구성원일 뿐 소유자가 아니면, 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 전체에서 고유해야 합니다. 미리 채워진 이름이 이미 사용 중이면, 3단계에서 다음을 클릭할 때 **GitHub App 만들기** "이름이 이미 사용 중입니다" 오류 툴팁이 다음에 표시됩니다 **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.