Google은 AI 기술을 사용하여 콘텐츠를 사용자의 기본 언어로 번역합니다. AI 번역에는 오류가 있을 수 있습니다.

보안 문제에 대한 기술 검사

에이전트 레지스트리를 사용하면 독립형 스킬에 대한 자동 보안 스캔을 구성하고, 조직 정책 서비스를 사용하여 조직 전체에 스캔 정책을 적용하고, 보안 발견 사항을 분류하여 손상된 스킬이 에이전트에 도달하지 않도록 방지할 수 있습니다.

스킬 버전을 업로드하면 에이전트 레지스트리가 SKILL.md 안내 파일, 선택적 스크립트, 지원 애셋에서 무단 데이터 무단 반출, 노출된 사용자 인증 정보, 프롬프트 인젝션과 같은 보안 위험을 스캔합니다.

스킬 보안 스캔은 대규모 언어 모델(LLM)을 사용하여 안내, 코드 로직, 시맨틱 의도를 평가합니다. LLM 분석은 확률적이므로 스캔에서 거짓양성 또는 거짓음성이 발생할 수 있으며 실행마다 결과가 다를 수 있습니다. 또한 발견 항목에 대한 세부정보는 대략적인 정보일 수 있으며 할루시네이션이 발생할 수 있습니다. 개발자는 수정 변경사항을 적용하기 전에 스캔 결과를 검토하고 확인해야 합니다.

시작하기 전에

Agent Registry 설정
단일 프로젝트 설정의 경우 Agent Registry가 사용 설정된 거버넌스 프로젝트의 프로젝트 ID를 가져옵니다. 여러 프로젝트에 관리 경계를 구성한 경우 경계 전체 검색 및 등록에 관리 프로젝트 ID를 사용하거나 단일 프로젝트 작업에 구성원 프로젝트 ID를 지정합니다.
Agent Registry에 독립형 스킬을 등록합니다.
이 문서의 Google Cloud CLI 명령어를 사용하려면 gcloud CLI 환경을 설정합니다.

필요한 역할

Agent Registry에서 스캔을 구성하고 발견 항목을 분류하는 데 필요한 권한을 얻으려면 관리자에게 Agent Registry가 사용 설정된 거버넌스 프로젝트에 대한 다음 IAM 역할을 부여해 달라고 요청하세요.

기술 스캔 구성: 에이전트 레지스트리 사용자(roles/agentregistry.user)
스킬 및 스킬 버전 보기: Agent Registry API 뷰어(roles/agentregistry.viewer)
보안 발견 사항 보기 및 나열: Agent Registry API 관리자(roles/agentregistry.admin)
조직 또는 폴더 수준에서 스캔 정책 적용: 조직 정책 관리자(roles/orgpolicy.policyAdmin)

역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.

커스텀 역할이나 다른 사전 정의된 역할을 통해 필요한 권한을 얻을 수도 있습니다.

다른 에이전트 레지스트리 역할에는 스캔을 구성하고 기술을 보는 데 필요한 권한이 포함될 수도 있습니다. 자세한 내용은 에이전트 레지스트리 역할 및 권한을 참조하세요.

압축되지 않은 페이로드 크기 제약 조건

최적의 성능을 보장하고 기본 LLM 스캐너의 처리 토큰 한도를 수용하기 위해 에이전트 레지스트리는 스캔이 활성 상태일 때 엄격한 비압축 크기 한도를 적용합니다.

압축되지 않은 총 기술 크기: 추출된 보관 파일의 경우 최대 10MB입니다.
파일당 압축되지 않은 크기: 기술 패키지 내 개별 파일의 경우 최대 1MB입니다.

스킬에 스캔이 사용 설정되어 있고 이러한 한도를 초과하면 스킬 버전 만들기가 INVALID_ARGUMENT 오류와 함께 실패하거나 버전의 스캔 상태가 UNSUPPORTED_FORMAT로 확인됩니다.

스캔이 명시적으로 사용 중지된 경우 에이전트 레지스트리는 이러한 스캔 관련 크기 한도를 우회하지만 일반적인 시스템 한도는 계속 적용됩니다. 시스템 한도에 대한 자세한 내용은 할당량 및 시스템 한도를 참조하세요.

스킬의 스캔 정책 구성

기본적으로 스킬은 사용 설정됨(차단)(ENABLED_BLOCKING) 스캔 정책을 사용합니다. 이 정책은 업로드된 스킬 버전에 무단 데이터 무단 반출, 노출된 사용자 인증 정보, 프롬프트 인젝션과 같은 보안 위험이 있는지 자동으로 스캔합니다. 감지된 문제는 거버넌스 프로젝트(projects/PROJECT_NUMBER/locations/LOCATION/findings/FINDING_ID)에서 읽기 전용 Finding 리소스로 노출됩니다.

사용 설정됨(차단)을 사용하면 에이전트 레지스트리에서 보안 발견 항목이 있는 버전의 다운로드를 차단하고 발견 항목이 있거나 스캔이 대기 중인 버전을 스킬의 기본 버전으로 승격하지 못하도록 합니다.

비차단 감사 모드(ENABLED_NONBLOCKING)에 대한 스캔 정책을 구성하거나 스캔(DISABLED)을 사용 중지할 수도 있습니다. 지원되는 스캔 정책에 대한 자세한 내용은 스캔 정책을 참조하세요.

스킬 스캔 설정 지정 또는 업데이트

기존 기술에서 스캔을 사용 설정하거나 업데이트하면 구성 변경 후에 생성된 기술 버전에만 적용됩니다. 이미 생성된 버전에 대해서는 스캔이 소급 트리거되지 않습니다. 스캔이 사용 중지되었을 때 업로드된 스킬 콘텐츠를 스캔하려면 새 스킬 버전을 만들어야 합니다.

스킬을 만들거나 업데이트할 때 스캔 설정을 구성하려면 다음 단계를 따르세요.

콘솔

Google Cloud 콘솔에서 에이전트 레지스트리 페이지로 이동합니다.

에이전트 레지스트리로 이동
기술 탭을 선택합니다.
기술 추가를 클릭하거나 기존 기술을 선택하고 수정을 클릭합니다.
보안 검사 섹션에서 원하는 검사 정책을 선택합니다.
저장 또는 만들기를 클릭합니다.

gcloud

스캔이 사용 설정된 스킬 만들기(차단): --scanning-policy 플래그를 enabled-blocking로 설정하여 gcloud agent-registry skills create 명령어를 실행합니다. 예를 들어 Cloud Storage 버킷의 ZIP 파일 보관 파일을 사용하여 스킬을 등록하는 경우 다음을 수행합니다.
```
gcloud agent-registry skills create SKILL_ID \
    --project=PROJECT_ID \
    --location=LOCATION \
    --target-state=disabled \
    --scanning-policy=enabled-blocking \
    --gcs-source-uri="gs://BUCKET_NAME/SKILL_PACKAGE.zip"
```
스캔이 사용 설정된 스킬 만들기(비차단): --scanning-policy 플래그를 enabled-nonblocking로 설정하여 gcloud agent-registry skills create 명령어를 실행합니다. 예를 들어 Cloud Storage 버킷의 ZIP 파일 보관 파일을 사용하여 스킬을 등록하는 경우 다음을 수행합니다.
```
gcloud agent-registry skills create SKILL_ID \
    --project=PROJECT_ID \
    --location=LOCATION \
    --target-state=disabled \
    --scanning-policy=enabled-nonblocking \
    --gcs-source-uri="gs://BUCKET_NAME/SKILL_PACKAGE.zip"
```
기존 기술의 스캔 정책 업데이트: --scanning-policy 플래그를 선택한 정책으로 설정하여 gcloud agent-registry skills update 명령어를 실행합니다(예: enabled-nonblocking).
```
gcloud agent-registry skills update SKILL_ID \
    --project=PROJECT_ID \
    --location=LOCATION \
    --scanning-policy=enabled-nonblocking
```

기술 검사 사용 중지: --scanning-policy 플래그를 disabled로 설정하여 gcloud agent-registry skills update 명령어를 실행합니다.

gcloud agent-registry skills update SKILL_ID \
    --project=PROJECT_ID \
    --location=LOCATION \
    --scanning-policy=disabled

기존 기술의 스캔 구성 설명: --format 플래그를 value(scanningConfig.policy)로 설정하여 gcloud agent-registry skills describe 명령어를 실행합니다.

gcloud agent-registry skills describe SKILL_ID \
    --project=PROJECT_ID \
    --location=LOCATION \
    --format="value(scanningConfig.policy)"

다음을 바꿉니다.

SKILL_ID: 기술의 ID입니다. 기존 수동 등록 스킬을 업데이트하거나 설명할 때는 private-my-skill과 같은 private- 프리픽스를 포함합니다.
PROJECT_ID: 프로젝트 ID입니다.
LOCATION: 레지스트리 위치입니다.
BUCKET_NAME: ZIP 번들이 포함된 Cloud Storage 버킷 이름입니다. 버킷에서 가져오기 전에 Agent Registry 서비스 에이전트에 버킷에 대한 storage.objects.get 권한이 있는지 확인합니다. 자세한 내용은 기술 등록을 참조하세요.
SKILL_PACKAGE: 스킬 페이로드가 포함된 스킬 패키지의 이름입니다.

REST

REST API를 사용하여 스캔을 구성하려면 요청 본문에 scanningConfig 객체를 포함합니다.

curl -X PATCH \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -d '{
        "scanningConfig": {
          "policy": "ENABLED_BLOCKING"
        }
      }' \
    "https://agentregistry.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID?updateMask=scanningConfig"

다음을 바꿉니다.

PROJECT_ID: 프로젝트 ID입니다.
LOCATION: 레지스트리 위치입니다.
SKILL_ID: 기술의 ID입니다. 수동으로 등록된 기술의 경우 private- 프리픽스(예: private-my-skill)를 포함합니다.

조직 정책 서비스를 사용하여 스캔 적용

스캔 정책을 평가하는 Skill 리소스에 커스텀 조직 정책 서비스 제약 조건을 정의하여 조직 전체 스캔 정책을 적용할 수 있으며, 선택적으로 Resource Manager 태그 예외를 적용할 수 있습니다.

Agent Registry의 조직 정책 시행, 기능, 제한사항에 대한 자세한 내용은 조직 정책 시행을 참조하세요.

커스텀 제약 조건 정의

다음 사양으로 skills-scan-constraint.yaml이라는 YAML 파일을 만듭니다.

name: organizations/ORGANIZATION_ID/customConstraints/custom.skillsScanningEnforcement
resourceTypes:
- agentregistry.googleapis.com/Skill
methodTypes:
- CREATE
- UPDATE
condition: resource.scanningConfig.policy == "DISABLED"
actionType: DENY
displayName: Prevent Disabling Skills Scanning
description: Prevents creating or updating skills with scanning disabled.

ORGANIZATION_ID를 숫자 조직 ID로 바꿉니다.

모든 기술에서 차단 모드를 요구하고 DISABLED 및 ENABLED_NONBLOCKING 스캔 정책을 모두 방지하려면 condition: resource.scanningConfig.policy == "ENABLED_BLOCKING" 및 actionType: ALLOW를 설정하면 됩니다.

커스텀 제약 조건 설정

gcloud org-policies set-custom-constraint 명령어를 사용하여 조직에 커스텀 제약 조건을 업로드하고 등록합니다.

gcloud org-policies set-custom-constraint skills-scan-constraint.yaml

조건부 예외가 있는 정책 적용

모든 표준 프로젝트에 제약 조건을 적용하는 동시에 exempt-scanning-enforcement: true로 태그를 지정한 테스트 프로젝트를 제외하는 skills-scan-policy.yaml라는 정책 정의 파일을 만듭니다.

name: organizations/ORGANIZATION_ID/policies/custom.skillsScanningEnforcement
spec:
  rules:
  # Enforce scanning on all standard projects
  - enforce: true
    condition:
      expression: "!resource.matchTag('ORGANIZATION_ID/exempt-scanning-enforcement', 'true')"
      title: "Enforce Scanning"
      description: "Enforce scanning on all non-exempt projects"
  # Bypass enforcement for tagged projects
  - enforce: false
    condition:
      expression: "resource.matchTag('ORGANIZATION_ID/exempt-scanning-enforcement', 'true')"
      title: "Exempt Testing Projects"
      description: "Allow scanning to be disabled for testing projects"

ORGANIZATION_ID를 숫자 조직 ID로 바꿉니다.

gcloud org-policies set-policy 명령어를 사용하여 조직에 정책을 적용합니다.

gcloud org-policies set-policy skills-scan-policy.yaml

정책 확인

gcloud org-policies describe 명령어를 사용하여 프로젝트에서 정책이 활성 상태인지 확인합니다.

gcloud org-policies describe custom.skillsScanningEnforcement \
    --project=PROJECT_ID \
    --effective

PROJECT_ID를 프로젝트 ID로 바꿉니다.

스캔 결과 및 수정 버전 상태 검토

스킬 버전을 게시하면 스캐너가 백그라운드에서 비동기식으로 실행됩니다. 버전 메타데이터를 검사하고 스캔 결과를 확인하려면 gcloud agent-registry skills revisions describe 명령어를 실행합니다.

gcloud agent-registry skills revisions describe REVISION_ID \
    --skill=SKILL_ID \
    --project=PROJECT_ID \
    --location=LOCATION

다음을 바꿉니다.

REVISION_ID: 스킬 버전의 ID입니다.
SKILL_ID: 기술 컨테이너의 ID입니다. 수동으로 등록된 기술의 경우 private-my-skill와 같은 private- 프리픽스를 포함합니다.
PROJECT_ID: 프로젝트 ID입니다.
LOCATION: 레지스트리 위치입니다.

출력에는 다음 예시와 같은 scanResult 블록이 포함됩니다.

name: projects/my-project/locations/us-central1/skills/private-my-skill/revisions/rev-v1
createTime: '2026-08-10T09:15:00.000000Z'
state: ACTIVE
scanResult:
  scanState: SUCCEEDED
  scanTime: '2026-08-10T09:16:22.000000Z'
  findings:
  - projects/my-project/locations/us-central1/findings/b9a8c7d6-e5f4-4321-89ab-cdef01234567

scanResult.scanState에 가능한 값은 다음과 같습니다.

SUCCEEDED: 스캔 실행이 완료되었습니다. 보안 문제가 감지되면 해당 리소스 이름이 scanResult.findings 배열에 나열됩니다. 감지된 문제가 없으면 scanResult.findings가 비어 있습니다.
RUNNING: 스캔이 실행 중입니다.
DISABLED: 스킬 버전이 생성될 때 스킬의 스캔 정책이 DISABLED로 설정되어 있으므로 스캔이 우회됩니다.
UNSUPPORTED_FORMAT: 업로드된 보관 파일을 스캐너로 분석할 수 없습니다. 예를 들어 압축되지 않은 크기가 스캔 한도를 초과했거나 보관 파일 형식이 지원되지 않기 때문입니다. 자세한 내용은 scanResult.errorMessage를 참고하세요.
FAILED: 내부 오류로 인해 스캔을 완료할 수 없습니다. 자세한 내용은 scanResult.errorMessage를 참조하세요.

버전의 스캔 상태는 버전이 생성된 시점에 활성 상태인 스캔 구성을 반영합니다. 스킬에서 스캔을 사용 설정하거나 업데이트하면 변경 후에 생성된 버전에만 적용되며 기존 버전에 대한 스캔이 소급하여 트리거되지 않습니다. 스캔이 사용 중지되었을 때 업로드된 기술 콘텐츠를 스캔하려면 새 기술 버전을 만들어야 합니다.

보안 발견 사항 분류

스캔에서 보안 문제가 감지되면 프로젝트 및 위치로 범위가 지정된 Finding 리소스로 Agent Registry에 자세한 원격 분석이 게시됩니다. 발견 항목을 보려면 Agent Registry API 관리자(roles/agentregistry.admin) 역할이 필요합니다.

기술 버전의 모든 발견 사항 나열: gcloud agent-registry findings list 명령어를 실행합니다.

gcloud agent-registry findings list \
    --project=PROJECT_ID \
    --location=LOCATION \
    --filter="resource=\"projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID/revisions/REVISION_ID\""

다음을 바꿉니다.

PROJECT_ID: 프로젝트 ID입니다.
LOCATION: 레지스트리 위치입니다.
SKILL_ID: 기술 컨테이너의 ID입니다(예: private-my-skill).
REVISION_ID: 스킬 버전의 ID입니다.

출력은 다음과 비슷합니다.

NAME                                                                                  SEVERITY           FINDING_CLASS  CREATE_TIME
projects/my-project/locations/us-central1/findings/FINDING_ID  SEVERITY_CRITICAL  VULNERABILITY  2026-08-10T09:16:22.104Z

발견 항목 세부정보 설명: gcloud agent-registry findings describe 명령어를 실행합니다.
```
gcloud agent-registry findings describe FINDING_ID \
    --project=PROJECT_ID \
    --location=LOCATION \
    --format=json
```
다음을 바꿉니다.
- FINDING_ID: Finding 리소스의 ID입니다.
- PROJECT_ID: 프로젝트 ID입니다.
- LOCATION: 레지스트리 위치입니다.
샘플 발견 항목 출력:
```
{
  "name": "projects/my-project/locations/us-central1/findings/FINDING_ID",
  "uid": "FINDING_ID",
  "createTime": "2026-08-10T09:16:22.104Z",
  "updateTime": "2026-08-10T09:16:22.104Z",
  "resource": "projects/my-project/locations/us-central1/skills/private-my-skill/revisions/rev-v1",
  "severity": "SEVERITY_CRITICAL",
  "findingClass": "VULNERABILITY",
  "files": [
    {
      "path": "resources/helper.py",
      "lineNumber": "12"
    }
  ],
  "detail": "Involves unauthorized outbound network requests transmitting sensitive local files or environment variables. Detected inside resources/helper.py at line 12."
}
```
각 Finding 리소스에는 다음 키 필드가 포함됩니다.
- resource: 발견 사항과 연결된 기술 버전의 전체 리소스 이름입니다.
- severity: 심각도 수준입니다. 허용되는 값은 다음과 같습니다.
  - SEVERITY_CRITICAL
  - SEVERITY_HIGH
  - SEVERITY_MEDIUM
  - SEVERITY_LOW
  - SEVERITY_UNSPECIFIED
- findingClass: 발견 항목 유형:
  - VULNERABILITY: 소프트웨어 또는 명령어 취약점
  - SECRET: 노출된 일반 텍스트 사용자 인증 정보, 키 또는 토큰
- files: 상대 path 및 lineNumber를 포함하여 기술 보관 파일에서 영향을 받는 파일 목록입니다. 0 값은 발견 항목이 전체 파일에 적용됨을 나타냅니다.
- detail: 감지된 보안 문제에 대한 자세한 설명입니다.

발견 항목 해결 및 기술 업데이트

스킬의 보안 발견 항목을 해결하려면 다음 단계를 따르세요.

발견 항목의 detail 필드를 검토하고 files 배열에서 문제가 되는 파일 path 및 lineNumber를 검사합니다. 자동 스캔은 LLM을 사용하여 시맨틱 코드와 명령어를 검사하므로 파일을 수정하기 전에 보고된 줄 번호와 발견 항목을 확인하세요.
로컬 개발 환경에서 소스 파일을 업데이트하여 발견 항목을 해결합니다. 예를 들어 승인되지 않은 네트워크 호출을 삭제하거나, 노출된 사용자 인증 정보를 삭제하거나, 프롬프트 인젝션 패턴을 삭제합니다.
업데이트된 파일을 새 ZIP 파일로 패키징합니다.
새 스킬 버전 만들기
새 버전의 scanResult.scanState가 발견 항목이 나열되지 않은 SUCCEEDED로 확인되는지 확인합니다.
스킬의 기본 버전을 업데이트하여 확인된 버전을 가리킵니다.

다음 단계

기술 아키텍처에 대해 알아보세요.
스킬 등록 방법 알아보기
기술 버전 관리 방법 알아보기
할당량 및 시스템 한도를 검토합니다.

보안 문제에 대한 기술 검사 컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

시작하기 전에

필요한 역할

압축되지 않은 페이로드 크기 제약 조건

스킬의 스캔 정책 구성

스킬 스캔 설정 지정 또는 업데이트

콘솔

gcloud

REST

조직 정책 서비스를 사용하여 스캔 적용

커스텀 제약 조건 정의

커스텀 제약 조건 설정

조건부 예외가 있는 정책 적용

정책 확인

스캔 결과 및 수정 버전 상태 검토

보안 발견 사항 분류

발견 항목 해결 및 기술 업데이트

다음 단계

보안 문제에 대한 기술 검사