에이전트에게 범위가 제한된 자격 증명 넘기기

이 문서는 Agent-Safe Change Control의 자격 증명 부분입니다. 에이전트가 안전하게 보유할 수 있는 키를 발급하고, 더 강력한 자격 증명을 유출하지 않고 넘기는 방법을 다룹니다. 집행 부분 — 예산, 레인, 위험 린트, 프로모트 정책 — 은 Guardrails입니다. 오늘 사용 가능합니다.

에이전트에 안전한 자격 증명이란 세 가지 경계 — 기능(capability), 범위(scope), 만료(expiry) — 를 가진 Kisenon API 키로, 깨끗한 환경에서 에이전트에게 넘겨집니다. 한 줄로 요약한 규칙: 에이전트의 자격 증명 범위를 제한하고, 에이전트가 접근할 수 있는 곳에 더 강력한 자격 증명을 남겨두지 마세요.

1. 범위가 제한된 에이전트 자격 증명 발급

세 차원이 모두 설정된 API 키를 발급합니다:

• capability = agent — 샌드박스를 구동할 수 있지만 keon connection-string main(및 모든 쓰기 가능 main 경로)은 403을 반환합니다. 에이전트는 변경을 제안할 수 있지만, 프로덕션에 쓰는 자격 증명은 결코 보유하지 않습니다.
• scope = project — 하나의 프로젝트로 한정됩니다. 유출되어도 다른 프로젝트에는 도달할 수 없습니다.
• expires_at(짧게) — 유출 시 폭발 반경이 제한됩니다. 영원이 아니라 며칠입니다.

콘솔에서 발급합니다 — kisenon.com의 Settings → API keys — 에서 Capability = agent, Scope = a project, Expires를 설정합니다. API 키는 로그인된 브라우저 세션에서 발급되며, 일반 CLI 키로는 다른 키를 발급할 수 없습니다. 쓰기 가능 main 경로에서 키를 사용하면 정확히 다음을 반환합니다:

agent-scoped API keys cannot retrieve data-plane credentials or perform
branch-admin role/database operations; use the sandbox flow

2. 에이전트에게 올바르게 넘기기

에이전트에게 범위가 제한된 키를 유일한 자격 증명으로, 깨끗한 셸이나 컨테이너 안에서 제공합니다:

export KEON_API_KEY=nsk_<agent-key>   # the scoped agent key, and ONLY this
unset DATABASE_URL                    # no full connection string in the env
# also: no personal `keon login` session (no ~/.config/keon/credentials.json),
# no ~/.pgpass, no admin DATABASE_URL reachable from the agent's process.

두 부분으로 된 규칙, 둘 다 필수입니다:

• 에이전트에게 넘기는 자격 증명의 범위를 제한하세요(1단계).
• 에이전트가 달리 주워 쓸 수 있는 더 강력한 자격 증명을 제거하세요 — 완전한 DATABASE_URL, ~/.pgpass, 또는 같은 셸에 로그인된 keon 세션.

3. 안전한 루프

에이전트는 제안하고, 사람 — 또는 자체의 제한된 프로모트 — 이 처리합니다:

keon sandbox run \
  --migrate "alembic upgrade head" \
  --verify  "pytest tests/db"

keon sandbox run은 브랜치를 포크하고, 격리된 홈에 수명이 짧은 에이전트 토큰을 발급하며, 명령에 포크의 범위가 제한된 URL을 DATABASE_URL로 주입합니다 — 그래서 샌드박스 안에서 keon connection-string main을 시도하는 명령조차 에이전트 키에 부딪혀 403을 받습니다. 캡처된 diff를 검토한 뒤, 프로젝트의 promote_mode에 따라 프로모트합니다:

keon projects update --promote-mode human으로 사람 검토를 켭니다.

이것이 무엇인가(그리고 무엇이 아닌가)

• 협력하는 에이전트를 위한 가드레일이지, 적대적 코드를 위한 감옥이 아닙니다. 자격 증명의 범위를 제한하는 것은 에이전트에게 넘기는 권한을 제한하지만, 이미 호스트 파일시스템이나 네트워크 접근 권한을 가진 하위 프로세스를 봉쇄하지는 않습니다. 실제 봉쇄 — 정리된 환경, 호스트 자격 증명 접근 차단, 샌드박스 엔드포인트로 한정된 이그레스 — 는 별도의 계층입니다. 에이전트의 코드가 신뢰할 수 없는 경우에는 이것도 추가하세요.
• cp가 main에 쓰는 유일한 주체입니다. 프로모트는 캡처된 문장을 서버 측에서 재생하며, 에이전트는 결코 쓰기 가능 main 자격 증명을 보유하지 않습니다.

비상 탈출(Break-glass)

설계상 특별한 "비상 탈출" 스위치는 없습니다. 직접 쓰기 가능 main 경로는 그저 사람이 보유한 일반 read_write 자격 증명(keon connection-string main, 또는 콘솔)일 뿐이며 — 의도적으로 에이전트 키에서 도달할 수 없습니다. 감사되는 사고 대응 경로가 필요하면, 운영자는 자신의 read_write 세션을 사용합니다. 모든 프로모트와 승인은 서버 측에서 귀속됩니다.