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

역량·프로젝트·만료로 범위를 한정한 API 키를 발급하고 AI 에이전트를 데이터베이스에 대해 안전하게 실행하세요.

이것은 AI 에이전트 샌드박스의 자격 증명 측면입니다. 에이전트가 안전하게 보유할 수 있는 키를 발급하는 방법과, 더 강력한 키를 유출하지 않고 그것을 넘기는 방법을 설명합니다. 오늘 바로 사용할 수 있습니다.

에이전트에게 안전한 자격 증명이란 세 가지 경계 — 역량, 범위, 만료 — 를 지니고 깨끗한 환경에서 에이전트에게 넘겨지는 Kisenon API 키입니다. 한 줄로 요약하면: 에이전트의 자격 증명 범위를 한정하고, 더 강력한 것을 에이전트가 닿을 수 있는 곳에 남겨두지 마세요.

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

세 가지 차원을 모두 설정하여 API 키를 발급합니다.

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

콘솔에서 발급하세요 — kisenon.com의 설정 → API 키 에서 역량 = agent, 범위 = 특정 프로젝트, 만료를 설정합니다. 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. 안전한 루프

에이전트가 제안하고, 사람 — 또는 에이전트 자신의 경계가 한정된 promote — 이 처리합니다.

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에 따라 promote 하세요.

`promote_mode`	Who commits to `main`
`self` (default)	검사가 통과하면 에이전트가 `keon sandbox promote <id>` 를 실행합니다.
`human`	에이전트가 제안하고, 소유자/관리자가 diff + 로그를 검토한 후 `keon sandbox approve <id>` 를 실행합니다.

keon projects update --promote-mode human 으로 사람 검토를 켜세요.

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

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

브레이크 글라스

설계상 특별한 "브레이크 글라스" 스위치는 없습니다. 쓰기 가능 main으로 가는 직접 경로는 사람이 보유한 일반 read_write 자격 증명일 뿐이며(keon connection-string main, 또는 콘솔) — 의도적으로 에이전트 키에서는 닿을 수 없게 되어 있습니다. 감사되는 사고 대응 경로에서는 운영자가 자신의 read_write 세션을 사용합니다. 모든 promote와 approve는 서버 측에서 귀속됩니다.