> 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/data-onboarding/supported-logs/entra-id-audit.md). # Microsoft Entra ID 감사 로그 ## 개요 Panther는 Microsoft Entra ID(이전의 Azure Active Directory) 감사 로그를 일반적인 [데이터 전송](/ko/data-onboarding/data-transports.md) 옵션, 예를 들어 Azure [Event Hub](/ko/data-onboarding/data-transports/azure/event-hub.md) 및 [Blob Storage](/ko/data-onboarding/data-transports/azure/blob-storage.md). ## Panther에 Microsoft Entra ID 감사 로그를 온보딩하는 방법 먼저 Panther에서 Azure Blob Storage 또는 Azure Event Hub 소스를 만든 다음, Azure를 구성하여 로그를 해당 위치로 내보내도록 합니다. ### 1단계: Panther에서 Microsoft Entra ID 소스 만들기 1. Panther Console의 왼쪽 탐색 표시줄에서 다음을 클릭합니다: **로그 소스**. 2. 클릭합니다 **새로 만들기**. 3. Microsoft Entra ID Audit를 검색한 다음 해당 타일을 클릭합니다. * 슬라이드아웃 패널에서 **전송 메커니즘** 오른쪽 상단의 드롭다운에는 다음이 미리 채워집니다 **Azure Event Hub** 옵션. 이 선택을 그대로 두거나 선택합니다. **Azure Blob Storage**. 4. 클릭합니다 **설정 시작**. 5. Panther의 지침에 따라 다음을 구성하세요 [Azure Event Hub](/ko/data-onboarding/data-transports/azure/event-hub.md) 또는 [Azure Blob Storage 소스](/ko/data-onboarding/data-transports/azure/blob-storage.md). {% hint style="info" %} 이 두 옵션은 지연 시간이 다릅니다. 다음을 선택하면 **Blob Storage** 옵션, Panther가 Entra ID 파일을 매시간 가져옵니다. 다음을 선택하면 **Event Hub**, 수집은 거의 실시간으로 이루어집니다. {% endhint %} * Azure Blob Storage를 선택하고 ...하는 동안 [2단계: 필요한 Azure 인프라 생성](/ko/data-onboarding/data-transports/azure/blob-storage.md#step-2-create-required-azure-infrastructure) Azure 리소스를 Terraform 대신 수동으로 만들기로 선택한 경우, 건 [Azure 컨테이너를 만드는 단계](https://docs.panther.com/data-onboarding/data-transports/azure/blob-storage#step-5-create-container-and-add-permission), 아래 2단계에서 스토리지 계정에 자동으로 생성되기 때문입니다. ### 2단계: Microsoft Entra ID 감사 로그 내보내기 Microsoft Defender XDR 로그를 Event Hub 또는 스토리지 계정으로 내보내려면 아래 지침을 따르세요: 1. Azure 대시보드에 로그인합니다. 2. 다음으로 이동하세요: **Microsoft Entra ID** 서비스**.** 3. 왼쪽 패널에서 클릭합니다 **감사 로그**. 4. 페이지 상단 근처에서 클릭합니다 **데이터 내보내기 설정**.\ ![The Microsoft Entra ID console is shown. An arrow is drawn from the "Audit logs" option in the navigation bar to a "Export data settings" button](https://docs.panther.com/~gitbook/image?url=https%3A%2F%2F4011785613-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252F-LgdiSWdyJcXPahGi9Rs-2910905616%252Fuploads%252Fgit-blob-494651d6c37ae5ccdbd7290e3daa2a91d525c7c5%252Fmicrosoft_entra_id.png%3Falt%3Dmedia\&width=300\&dpr=4\&quality=100\&sign=9bd4e213\&sv=2) 5. 클릭합니다 **진단 설정 추가**. 6. 다음 페이지에서 **진단 설정** 페이지에서 다음 값을 설정합니다: * **진단 설정 이름**: 설명적인 이름을 입력하세요. * **카테고리** (아래 **로그**): 다음 확인란을 선택합니다: * **AuditLogs** * **SignInLogs** * **NonInteractiveUserSignInLogs** * **ServicePrincipalSignInLogs** * **ManagedIdentitySignInLogs** * **대상 세부 정보**: 다음 중 하나를 선택합니다 **스토리지 계정에 보관** 또는 **이벤트 허브로 스트리밍**, Panther에서 만든 로그 소스 유형에 따라 [1단계](#step-1-create-the-microsoft-entra-id-source-in-panther). * 선택한 경우 **스토리지 계정에 보관**에서 **스토리지 계정** 필드에서 스토리지 계정을 선택합니다. * 선택한 경우 **이벤트 허브로 스트리밍**에서 **Event Hub 네임스페이스** 필드에서 Event Hub를 선택합니다.
7. 왼쪽 위 모서리에서 클릭합니다 **저장**. ### (Blob Storage 전송만 해당) 3단계: 컨테이너에 역할 할당 {% hint style="warning" %} 이 단계는 1단계에서 Azure Blob Storage를 선택한 경우에만 적용됩니다. Azure Event Hub를 사용한 경우 이 단계를 건너뜁니다. {% endhint %} 1. 새로 만든 컨테이너를 클릭한 다음, 왼쪽 탐색 모음에서 다음을 클릭합니다 **액세스 제어(IAM)**. 2. 클릭합니다 **+추가**.\ ![In the panthertestcontainer3 Access Control (IAM) page, an arrow is drawn to the +Add button](/files/3d9979bcb075fda233831f277fdf2686ed69ad28) 3. 클릭합니다 **역할 할당 추가**. 4. "Storage Blob Data Reader"를 검색하고 표시되는 일치하는 역할을 선택합니다.\ ![In the Add role assignment page of the Azure console, "storage blob" has been searched for in the search box. One of the results, Storage Blob Data Reader, is circled.](/files/9f890ad23deede1d5cac7a8c69456b57e6e59a24) 5. 다음을 클릭하세요: **구성원** 탭. 6. 클릭합니다 **+구성원 선택**. 7. ... 중에 만든 등록된 앱의 이름을 검색합니다. [Azure Blob Storage 소스에서 필요한 Azure 인프라 생성 프로세스](/ko/data-onboarding/data-transports/azure/blob-storage.md#step-2-create-required-azure-infrastructure), 그리고 다음을 클릭합니다 **선택**. 8. 클릭합니다 **검토+할당**. ## Panther가 관리하는 디택션 참고 [Panther가 관리하는](https://docs.panther.com/detections/panther-managed) Azure용 규칙은 ...에서 [panther-analysis GitHub 저장소](https://github.com/panther-labs/panther-analysis/tree/master/rules/azure_signin_rules). ## 지원되는 로그 유형 Panther는 Microsoft Entra ID 감사 및 로그인 로그를 지원하며, 이는 [Azure.Audit](#azure.audit) 스키마입니다. ### Azure.Audit Azure.Audit 로그 스키마는 Microsoft Entra ID 감사 로그 및 로그인 로그를 포함합니다. 자세한 내용은 Microsoft 설명서를 참조하세요: * 참고 [감사 로그에 대한 일반 정보는 이 페이지를 참조하세요](https://learn.microsoft.com/en-us/entra/identity/monitoring-health/concept-audit-logs), 및 [감사 로그 참조를 보려면 이 페이지를 참조하세요](https://learn.microsoft.com/en-us/entra/identity/monitoring-health/reference-audit-activities). * 참고 [로그인 로그에 대한 일반 정보는 이 페이지를 참조하세요](https://learn.microsoft.com/en-us/entra/identity/monitoring-health/concept-sign-ins), 및 [로그인 로그 스키마를 보려면 이 페이지를 참조하세요](https://learn.microsoft.com/en-us/azure/azure-monitor/reference/tables/signinlogs). ```yaml 스키마: Azure.Audit 설명: Azure Active Directory의 감사 로그 referenceURL: https://learn.microsoft.com/en-us/azure/active-directory/reports-monitoring/concept-audit-logs 필드: - 이름: Level 설명: 이벤트의 심각도 수준 또는 유형(예: 정보, 오류). 유형: string - 이름: callerIpAddress 설명: 이벤트가 시작된 IP 주소. 유형: string 지표: - ip - 이름: category 설명: 이벤트의 카테고리 분류(예: SignInLogs, AuditLogs). 유형: string - name: correlationId 설명: 여러 관련 이벤트를 상호 연관시키는 고유 식별자. 유형: string 지표: - trace_id - 이름: durationMs 설명: 작업을 완료하는 데 걸린 총 시간(밀리초). 유형: float - 이름: identity 설명: 사용자, 애플리케이션 또는 서비스 프린시펄의 식별자. 유형: string - 이름: location 설명: 이벤트가 발생한 지리적 위치 또는 지역. 유형: string - 이름: locationDetails 유형: json - 이름: networkLocationDetails 유형: json - name: operationName 필수: true 설명: 수행된 작업 또는 API 호출의 이름. 유형: string - 이름: operationVersion 설명: 작업 또는 API의 버전 번호. 유형: string - name: time 설명: 이벤트가 발생한 타임스탬프. 유형: timestamp 시간 형식: - rfc3339 - '%m/%d/%Y %I:%M:%S %p' 이벤트 시간 여부: true - name: properties 설명: 이벤트에 대한 추가 속성과 세부 정보가 포함된 중첩 객체. 유형: object 필드: - 이름: aadTenantId 유형: string - 이름: activityDateTime 설명: 활동의 날짜 및 시간. 유형: timestamp 시간 형식: - rfc3339 - 이름: activityDisplayName 설명: 활동의 사용자 친화적 표시 이름. 유형: string - 이름: additionalDetails 설명: 추가 컨텍스트 또는 메타데이터가 포함된 키-값 쌍 배열. 유형: array 요소: 유형: object 필드: - 이름: key 유형: string - 이름: value 유형: string - 이름: alternateSignInName 설명: 제공된 경우 대체 사용자 로그인 이름. 유형: string 지표: - username - 이름: appDisplayName 설명: 관련된 애플리케이션의 표시 이름. 유형: string - 이름: appliedConditionalAccessPolicies 설명: 적용된 조건부 액세스 정책 및 결과 목록. 유형: json - 이름: appliedEventListeners 유형: json - 이름: 앱 ID 설명: 이벤트와 연결된 애플리케이션 ID. 유형: string - 이름: appServicePrincipalId 유형: string - 이름: authenticationAppDeviceDetails 유형: json - 이름: authenticationStrengths 유형: json - 이름: authenticationAppPolicyEvaluationDetails 유형: json - 이름: authenticationContextClassReferences 유형: json - 이름: authenticationDetails 유형: json - 이름: authenticationMethodsUsed 유형: json - 이름: authenticationProcessingDetails 유형: json - 이름: authenticationProtocol 유형: string - 이름: authenticationRequirement 유형: string - 이름: authenticationRequirementPolicies 유형: json - 이름: autonomousSystemNumber 유형: string - 이름: _billedSize 유형: float - 이름: category 유형: string - 이름: clientAppUsed 유형: string - 이름: clientCredentialType 유형: string - 이름: conditionalAccessAudiences 유형: json - 이름: conditionalAccessPolicies 유형: json - 이름: conditionalAccessStatus 유형: string - name: correlationId 유형: string - 이름: createdDateTime 유형: timestamp 시간 형식: - rfc3339 - 이름: crossTenantAccessType 유형: string - 이름: deviceDetail 유형: json - 이름: federatedCredentialId 유형: string - 이름: flaggedForReview 유형: boolean - 이름: globalSecureAccessIpAddress 유형: string - 이름: homeTenantId 유형: string - 이름: homeTenantName 유형: string - 이름: id 유형: string - 이름: incomingTokenType 유형: string - 이름: ipAddress 설명: 중첩된 리소스와 연결된 IP 주소. 유형: string 지표: - ip - 이름: ipAddressFromResourceProvider 설명: 기본 리소스 공급자가 기록한 IP 주소. 유형: string 지표: - ip - 이름: _isBillable 유형: string - 이름: isDeleted 설명: 엔터티가 삭제되었는지 여부. 유형: boolean - 이름: initiatedBy 설명: 이벤트를 시작한 행위자(사용자 또는 앱). 유형: object 필드: - 이름: app 유형: object 필드: - name: displayName 유형: string - 이름: servicePrincipalId 유형: string - 이름: 앱 ID 설명: 애플리케이션 등록/클라이언트 ID. 유형: string - 이름: user 설명: 작업을 수행한 사용자. 유형: object 필드: - 이름: id 설명: 사용자의 개체 ID. 유형: string - name: displayName 설명: Azure AD에 표시되는 사용자의 이름. 유형: string 지표: - username - 이름: userPrincipalName 설명: 사용자의 User Principal Name(UPN). 유형: string - 이름: ipAddress 설명: 사용자가 작업을 수행한 IP 주소. 유형: string 지표: - ip - 이름: roles 유형: json - 이름: isProcessing 설명: 이벤트가 아직 처리 중인지 여부. 유형: boolean - 이름: loggedByService 설명: 이 이벤트를 기록한 Microsoft 서비스(예: AzureAD). 유형: string - 이름: location 설명: JSON 객체로 표현된 지리적 또는 물리적 위치 정보. 유형: json - 이름: networkLocationDetails 설명: 이벤트에 관련된 네트워크 위치에 대한 세부 정보. 유형: json - 이름: operationType 설명: 수행된 작업의 유형. 유형: string - 이름: result 설명: 작업의 결과 상태. 유형: string - 이름: resultReason 설명: 작업 결과에 대한 추가 사유 또는 코드. 유형: string - 이름: isInteractive 설명: 로그인이 대화형인지 여부를 나타냅니다. 유형: boolean - 이름: isRisky 유형: boolean - 이름: isTenantRestricted 설명: 테넌트 제한이 적용되었는지 여부. 유형: boolean - 이름: isThroughGlobalSecureAccess 설명: 이벤트가 Global Secure Access를 통해 라우팅되었는지 여부. 유형: boolean - 이름: originalRequestId 설명: 이것이 체인의 일부인 경우 원래 요청의 요청 ID. 유형: string - 이름: originalTransferMethod 설명: 원래 요청의 전송 방법. 유형: string - 이름: privateLinkDetails 유형: json - 이름: processingTimeInMilliseconds 설명: 이벤트를 처리하는 데 걸린 시간. 유형: bigint - 이름: resource 유형: string - name: resourceDisplayName 설명: 리소스의 표시 이름. 유형: string - 이름: resourceGroup 유형: string - 이름: resourceId 설명: 액세스된 리소스의 개체 ID. 유형: string - 이름: resourceIdentity 유형: string - 이름: resourceProvider 유형: string - 이름: resourceOwnerTenantId 설명: 리소스 소유자의 테넌트 ID. 유형: string - 이름: resourceServicePrincipalId 설명: 액세스된 리소스의 서비스 프린시펄 개체 ID. 유형: string - 이름: resourceTenantId 설명: 액세스된 리소스의 테넌트 ID. 유형: string - 이름: riskEventTypes 설명: 이 이벤트에 대해 감지된 위험 이벤트 유형 목록. 유형: json - 이름: riskEventTypes_v2 설명: 강화된 위험 이벤트 유형 목록. 유형: json - 이름: riskLastUpdatedDateTime 설명: 마지막 위험 업데이트의 타임스탬프. 유형: timestamp 시간 형식: - rfc3339 - 이름: riskDetail 설명: 감지된 위험의 성격에 대한 세부 정보. 유형: string - 이름: riskLevel 설명: 분석 후 최종 위험 수준. 유형: string - 이름: riskLevelAggregated 설명: 이벤트에 할당된 집계 위험 수준. 유형: string - 이름: riskLevelDuringSignIn 설명: 로그인 시점의 위험 수준. 유형: string - 이름: riskState 설명: 사용자 또는 세션의 위험 상태. 유형: string - 이름: rngcStatus 설명: 요청 nonce 생성 검사에 대한 상태 코드. 유형: string - 이름: servicePrincipalId 설명: 사용된 서비스 프린시펄의 개체 ID. 유형: string - 이름: servicePrincipalCredentialKeyId 설명: 서비스 프린시펄이 사용한 자격 증명의 키 ID. 유형: string - 이름: servicePrincipalName 설명: 서비스 프린시펄의 이름. 유형: string - 이름: sessionId 설명: 작업의 세션 식별자. 유형: string - 이름: sessionLifetimePolicies 설명: 이 작업의 세션 수명을 관리하는 정책. 유형: json - 이름: signInIdentifier 설명: 사용자를 인증하는 데 사용되는 기본 식별자. 유형: string - 이름: signInIdentifierType 유형: string - 이름: signInTokenProtectionStatus 설명: 로그인 시 토큰 보호 상태. 유형: string - 이름: sourceSystem 유형: json - 이름: ssoExtensionVersion 설명: SSO 브라우저 확장 프로그램의 버전. 유형: string - 이름: status 설명: 로그인 시도에 대한 상태 세부 정보. 유형: json - 이름: targetResources 설명: 작업의 대상이 되었거나 영향을 받은 리소스 배열. 유형: array 요소: 유형: object 필드: - name: displayName 설명: 리소스의 표시 이름. 유형: string - 이름: id 설명: 리소스의 고유 개체 ID. 유형: string - 이름: modifiedProperties 설명: 수정된 리소스 속성. 유형: array 요소: 유형: object 필드: - 이름: oldValue 설명: 속성의 이전 값. 유형: string - name: displayName 설명: 수정된 속성의 이름. 유형: string - 이름: newValue 설명: 속성의 새 값. 유형: string - 이름: type 설명: 리소스 유형(예: User, Group, App). 유형: string - 이름: administrativeUnits 유형: json - 이름: groupType 설명: 그룹 리소스의 유형(해당하는 경우). 유형: string - 이름: userPrincipalName 설명: 리소스 내 사용자의 UPN. 유형: string - name: tenantId 설명: Azure AD 테넌트의 테넌트 ID. 유형: string - 이름: timeGenerated 설명: 이 로그 항목이 생성된 날짜와 시간. 유형: timestamp 시간 형식: - rfc3339 이벤트 시간 여부: true - 이름: tokenIssuerName 설명: 토큰을 발급한 기관의 이름. 유형: string - 이름: tokenIssuerType 설명: 토큰 발급자 유형. 유형: string - 이름: tokenProtectionStatusDetails 설명: 토큰 보호 상태에 대한 정보. 유형: json - 이름: type 유형: string - 이름: uniqueTokenIdentifier 설명: 보안 토큰의 고유 식별자. 유형: string - name: userAgent 설명: 클라이언트의 사용자 에이전트 문자열. 유형: string - 이름: userDisplayName 설명: 사용자의 표시 이름. 유형: string 지표: - username - 이름: userId 설명: Azure AD의 사용자 개체 ID. 유형: string - 이름: userPrincipalName 설명: 사용자의 UPN. 유형: string 지표: - username - email - 이름: userType 유형: string - 이름: activity 설명: 이벤트와 관련된 활동의 이름 또는 유형. 유형: string - 이름: additionalInfo 설명: 이벤트에 대한 추가 정보. 유형: string - 이름: detectedDateTime 설명: 위험 또는 디택션이 처음 관찰된 날짜와 시간. 유형: timestamp 시간 형식: - rfc3339 - 이름: 디택션TimingType 설명: 위험 디택션의 시점 컨텍스트(예: 실시간, 오프라인). 유형: string - 이름: lastUpdatedDateTime 설명: 이 이벤트가 마지막으로 업데이트된 날짜와 시간. 유형: timestamp 시간 형식: - rfc3339 - 이름: mitreTechniqueId 설명: 이벤트와 관련된 MITRE ATT&CK 기법 식별자(사용 가능한 경우). 유형: string 지표: - mitre_attack_technique - 이름: riskEventType 설명: 활동과 관련된 위험 이벤트 유형(예: UnfamiliarLocation). 유형: string - 이름: riskType 설명: 감지된 위험 유형의 분류. 유형: string - name: source 설명: 이 로그 항목의 원본 Microsoft 서비스 또는 구성 요소. 유형: string - 이름: identity 설명: 이 중첩 이벤트와 관련된 ID. 유형: string - name: operationName 설명: 속성 컨텍스트에서 작업의 이름. 유형: string - name: resultDescription 설명: 작업 결과에 대한 더 자세한 설명. 유형: string - name: resultType 설명: 작업의 상위 수준 결과(성공, 실패 등). 유형: string - 이름: C_DeviceId 설명: 이벤트와 연결된 디바이스 ID. 유형: string - 이름: C_Sid 설명: 이벤트와 연결된 보안 식별자(SID). 유형: string - 이름: C_Iat 설명: 이벤트의 발급 시각 타임스탬프 또는 ID. 유형: string - 이름: C_Idtyp 설명: 이벤트와 연결된 ID 유형 코드. 유형: string - 이름: UserPrincipalObjectID 설명: 사용자 프린시펄의 개체 ID. 유형: string - 이름: __UDI_RequiredFields_EventTime 설명: 이벤트가 발생한 Unix 타임스탬프. 유형: timestamp 시간 형식: - unix_auto - 이름: __UDI_RequiredFields_RegionScope 설명: 이벤트의 지역 범위. 유형: string - 이름: __UDI_RequiredFields_TenantId 설명: UDI 준수에 필요한 테넌트 ID. 유형: string - 이름: __UDI_RequiredFields_UniqueId 설명: UDI 컨텍스트에서 이벤트의 고유 식별자. 유형: string - 이름: apiVersion 설명: 작업에 사용된 API 버전. 유형: string - 이름: atContentH 설명: 추가 토큰 또는 컨텍스트 정보(헤더). 유형: string - 이름: atContentP 설명: 추가 토큰 또는 컨텍스트 정보(페이로드). 유형: string - 이름: clientAuthMethod 설명: 사용된 클라이언트 인증 방법(예: 클라이언트 시크릿, 인증서). 유형: string - 이름: clientRequestId 설명: 클라이언트 요청의 고유 식별자. 유형: string - 이름: durationMs 설명: 속성 내 작업의 지속 시간(밀리초). 유형: float - name: identityProvider 설명: 인증에 관련된 ID 공급자. 유형: string - 이름: operationId 설명: 작업 식별자. 유형: string - name: requestMethod 설명: 작업에 사용된 HTTP 메서드(GET, POST 등). 유형: string - name: requestUri 설명: 액세스한 API 또는 리소스의 URI. 유형: string - 이름: responseSizeBytes 설명: 응답 크기(바이트). 유형: bigint - name: responseStatusCode 설명: 응답의 HTTP 상태 코드. 유형: bigint - 이름: roles 설명: 사용자 또는 애플리케이션에 할당된 역할. 유형: string - 이름: scopes 설명: 작업에서 요청한 OAuth 범위. 유형: string - 이름: signInActivityId 설명: 고유 로그인 활동 식별자. 유형: string - 이름: tokenIssuedAt 설명: 토큰이 발급된 시간. 유형: timestamp 시간 형식: - rfc3339 - 이름: wids 설명: 관련된 알려진 ID 또는 기타 식별자. 유형: string - name: requestId 설명: 고유한 요청 식별자. 유형: string - 이름: appOwnerTenantId 설명: 애플리케이션 소유자의 테넌트 ID. 유형: string - 이름: servicePrincipalCredentialThumbprint 설명: 서비스 주체에서 사용한 자격 증명의 지문. 유형: string - 이름: mfaDetail 설명: 다단계 인증 단계에 대한 세부 정보. 유형: object 필드: - 이름: authDetail 설명: 인증 프로세스에 대한 세부 정보. 유형: string - 이름: authMethod 설명: 사용된 MFA 방법(예: 전화, 앱). 유형: string - 이름: resourceId 설명: 이벤트와 관련된 Azure 리소스의 고유 식별자. 유형: string - name: resultDescription 설명: 이벤트 결과에 대한 추가 맥락 또는 설명. 유형: string - 이름: resultSignature 설명: 이벤트 결과의 서명 또는 고유 식별자. 유형: string - name: resultType 설명: 성공, 실패 또는 시간 초과와 같은 이벤트의 전체 결과. 유형: string - name: tenantId 설명: 이벤트가 발생한 Azure Active Directory 테넌트의 테넌트 ID. 유형: string ``` --- # 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/data-onboarding/supported-logs/entra-id-audit.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.