접근 제어·승인 도구
이 도구들은 API 토큰이나 서비스 토큰이 무엇을 할 수 있는지 결정하는 권한 계층과, 실행 전 사람의 결정이 필요한 작업의 승인 흐름을 관리합니다. “이 토큰이 web-01에서 docker 명령을 실행할 수 있어?”, “CI 토큰이 접근 가능한 서버는 어디야?”, “아직 승인 대기 중인 게 뭐가 있어?” 같은 요청을 처리합니다.
명령·서버·파일 ACL 규칙은 명령 실행 도구와 파일 전송 도구가 동작하기 위한 전제 조건입니다. 일치하는 ACL 규칙이 없으면 토큰이 다른 조건을 모두 충족해도 거부됩니다. 승인 요청과 sudo 정책은 별개의 관심사로, 상위 권한이나 사람의 승인이 필요한 작업을 다룹니다. 대부분 명령 실행의 승인 대기 결과나 작업 세션에서 나타납니다.
모든 도구는 workspace(필수)와 region(선택, 기본값은 설정된 리전)을 받습니다. 이 공통 파라미터는 아래 표에서 생략합니다.
요약
| 도구 | 설명 | 접근 수준 |
|---|---|---|
list_command_acls | 명령 ACL 규칙 목록 조회 | 읽기 전용 |
create_command_acl | 명령 ACL 규칙 생성 | 추가적 |
update_command_acl | 명령 ACL 규칙 수정 | 멱등적 쓰기 |
delete_command_acl | 명령 ACL 규칙 삭제 | 파괴적 |
list_server_acls | 서버 ACL 규칙 목록 조회 | 읽기 전용 |
create_server_acl | 서버 ACL 규칙 생성 | 추가적 |
update_server_acl | 서버 ACL 규칙 수정 | 멱등적 쓰기 |
delete_server_acl | 서버 ACL 규칙 삭제 | 파괴적 |
bulk_server_acl | 여러 서버의 서버 ACL 항목을 한 번에 추가·삭제 | 파괴적 |
list_file_acls | 파일 ACL 규칙 목록 조회 | 읽기 전용 |
create_file_acl | 파일 ACL 규칙 생성 | 추가적 |
update_file_acl | 파일 ACL 규칙 수정 | 멱등적 쓰기 |
delete_file_acl | 파일 ACL 규칙 삭제 | 파괴적 |
list_approval_requests | 대기 중·과거 승인 요청 목록 조회 | 읽기 전용 |
get_approval_request | 특정 승인 요청의 상세 정보 조회 | 읽기 전용 |
explain_approval_decision | 승인·거부가 사람만 할 수 있는 작업임을 설명 | 읽기 전용 |
list_sudo_policies | sudo 정책 목록 조회 | 읽기 전용 |
create_sudo_policy | sudo 정책 생성 | 추가적 |
명령 ACL
명령 ACL 규칙은 토큰이 execute_command로 실행할 수 있는 셸 명령 패턴을 제어합니다. 각 규칙은 정확히 하나의 토큰(API 토큰 또는 서비스 토큰, 둘 다는 불가)에 연결되며, 선택적으로 시스템 사용자명이나 그룹으로 범위를 제한할 수 있습니다.
list_command_acls
워크스페이스에 설정된 명령 ACL 규칙을 조회합니다. api_token_id나 service_token_id로 필터링하면 특정 토큰의 규칙만 볼 수 있습니다(둘 다 지정하면 오류가 발생합니다). 명령 실행 권한을 확인하거나 execute_command에서 발생한 403 오류를 디버깅할 때 사용합니다.
접근 수준: 읽기 전용
파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
api_token_id | string | 아니오 | API 토큰 ID로 필터링(service_token_id와 상호 배타적) |
service_token_id | string | 아니오 | 서비스 토큰 ID로 필터링(api_token_id와 상호 배타적) |
page | integer | 아니오 | 페이지네이션 페이지 번호 |
page_size | integer | 아니오 | 페이지당 항목 수 |
예시
“CI 토큰이
docker ps를 실행하면 왜 거부되지?”
에이전트는 api_token_id를 CI 토큰의 ID로 설정해 list_command_acls를 호출하고, docker *(또는 정확히 docker ps)와 일치하는 규칙이 있는지 확인합니다.
create_command_acl
토큰이 docker *나 ls -la 같은 패턴에 맞는 명령을 실행할 수 있도록 허용하는 명령 ACL 규칙을 생성합니다. api_token_id나 service_token_id 중 정확히 하나를 지정해야 하며, 규칙은 그 토큰에 연결됩니다.
접근 수준: 추가적
파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
command | string | 예 | 허용할 명령 패턴(예: docker *, ls -la). * 와일드카드 지원 |
api_token_id | string | 조건부 | 이 규칙이 적용될 API 토큰(service_token_id와 상호 배타적, 둘 중 하나 필수) |
service_token_id | string | 조건부 | 이 규칙이 적용될 서비스 토큰(api_token_id와 상호 배타적, 둘 중 하나 필수) |
username | string | 아니오 | 시스템 사용자명 제한. 비워두면(기본값) 토큰 소유자로만 제한되고, *는 모든 사용자를 허용 |
groupname | string | 아니오 | 시스템 그룹명 제한. 비워두면(기본값) 제한이 없음 |
예시
“배포 토큰이 접근 가능한 서버에서 모든
docker명령을 실행하게 해줘”
에이전트는 command="docker *"와 배포 토큰의 ID를 api_token_id로 설정해 create_command_acl을 호출합니다.
update_command_acl
기존 명령 ACL 규칙의 명령 패턴이나 사용자명·그룹명 제한을 수정합니다. 최소 하나의 필드는 변경해야 합니다. 이 규칙의 토큰 연결은 여기서 바꿀 수 없으며, 다른 토큰에 연결하려면 규칙을 삭제하고 다시 생성해야 합니다.
접근 수준: 멱등적 쓰기
파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
acl_id | string | 예 | 수정할 명령 ACL 규칙 ID |
command | string | 아니오 | 새로 허용할 명령 패턴 |
username | string | 아니오 | 시스템 사용자명 제한. 기존 제한을 지우려면 ''를 명시적으로 전달하고, 변경하지 않으려면 생략 |
groupname | string | 아니오 | 시스템 그룹명 제한. 기존 제한을 지우려면 ''를 명시적으로 전달하고, 변경하지 않으려면 생략 |
예시
“그 명령 ACL 규칙을
docker ps만이 아니라 모든docker하위 명령을 허용하도록 넓혀줘”
에이전트는 list_command_acls로 규칙을 찾은 뒤, 그 규칙의 acl_id와 command="docker *"로 update_command_acl을 호출합니다.
delete_command_acl
명령 ACL 규칙을 영구적으로 삭제합니다. 되돌릴 수 없으며, 토큰은 즉시 그 규칙이 부여한 권한을 잃습니다.
접근 수준: 파괴적
파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
acl_id | string | 예 | 삭제할 명령 ACL 규칙 ID |
예시
“CI 토큰의
rm명령 실행 권한을 회수해줘”
에이전트는 list_command_acls로 일치하는 규칙을 찾아 사용자에게 확인받은 뒤, 그 규칙의 acl_id로 delete_command_acl을 호출합니다.
서버 ACL
서버 ACL 규칙은 토큰이 어떤 서버에든 접근할 수 있는지 자체를 제어합니다. 명령 ACL이나 파일 ACL 규칙이 무엇이든, 서버에서 명령을 실행하거나 파일을 전송하려면 먼저 이 규칙을 통과해야 합니다.
list_server_acls
워크스페이스에 설정된 서버 ACL 규칙을 조회합니다. api_token_id나 service_token_id로 필터링하면 특정 토큰이 접근 가능한 서버를 볼 수 있습니다(둘 다 지정하면 오류가 발생합니다).
접근 수준: 읽기 전용
파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
api_token_id | string | 아니오 | API 토큰 ID로 필터링(service_token_id와 상호 배타적) |
service_token_id | string | 아니오 | 서비스 토큰 ID로 필터링(api_token_id와 상호 배타적) |
page | integer | 아니오 | 페이지네이션 페이지 번호 |
page_size | integer | 아니오 | 페이지당 항목 수 |
예시
“모니터링 토큰이 접근 가능한 서버는 어디야?”
에이전트는 api_token_id를 모니터링 토큰의 ID로 설정해 list_server_acls를 호출하고, 반환된 서버 목록을 나열합니다.
create_server_acl
토큰에게 특정 서버 하나에 대한 접근 권한을 부여하는 서버 ACL 규칙을 생성합니다. api_token_id나 service_token_id 중 정확히 하나를 지정해야 합니다. 여러 서버에 한 번에 접근 권한을 부여하려면 bulk_server_acl을 사용하세요.
접근 수준: 추가적
파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
server_id | string | 예 | 접근 권한을 부여할 서버 UUID |
api_token_id | string | 조건부 | 접근 권한을 부여할 API 토큰(service_token_id와 상호 배타적, 둘 중 하나 필수) |
service_token_id | string | 조건부 | 접근 권한을 부여할 서비스 토큰(api_token_id와 상호 배타적, 둘 중 하나 필수) |
예시
“배포 토큰에게 web-01 접근 권한을 줘”
에이전트는 server_id를 web-01의 UUID로, api_token_id를 배포 토큰의 ID로 설정해 create_server_acl을 호출합니다.
update_server_acl
기존 서버 ACL 규칙을 수정합니다. 명령 ACL·파일 ACL 규칙과 달리 서버 ACL 규칙은 토큰 연결을 여기서 바꿀 수 있습니다. api_token_id를 지정하면 규칙이 그 API 토큰에 다시 연결되며(기존 서비스 토큰 연결은 제거) service_token_id를 지정하면 반대로 동작합니다.
접근 수준: 멱등적 쓰기
파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
acl_id | string | 예 | 수정할 서버 ACL 규칙 ID |
server_id | string | 아니오 | 새 서버 UUID |
api_token_id | string | 아니오 | 이 규칙을 다시 연결할 새 API 토큰(service_token_id와 상호 배타적) |
service_token_id | string | 아니오 | 이 규칙을 다시 연결할 새 서비스 토큰(api_token_id와 상호 배타적) |
예시
“그 서버 ACL 규칙을 예전 CI 토큰에서 새 토큰으로 옮겨줘”
에이전트는 규칙의 acl_id와 새 토큰의 ID를 api_token_id로 설정해 update_server_acl을 호출합니다.
delete_server_acl
서버 ACL 규칙을 영구적으로 삭제합니다. 되돌릴 수 없으며, 토큰은 즉시 해당 서버 접근 권한을 잃습니다.
접근 수준: 파괴적
파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
acl_id | string | 예 | 삭제할 서버 ACL 규칙 ID |
예시
“외부 계약자 토큰의 db-01 접근 권한을 제거해줘”
에이전트는 list_server_acls로 일치하는 규칙을 찾아 사용자에게 확인받은 뒤, 그 규칙의 acl_id로 delete_server_acl을 호출합니다.
bulk_server_acl
한 번의 호출로 최대 100대 서버의 서버 ACL 항목을 추가하거나 삭제합니다. create_server_acl이나 delete_server_acl을 반복 호출하는 것의 일괄 처리 버전입니다. api_token_id나 service_token_id 중 정확히 하나를 지정해야 합니다.
이 도구는 action="add"일 때도 항상 파괴적으로 분류됩니다. 분류는 도구 전체에 고정되어 있고, 삭제 경로가 더 중대한 영향을 미치기 때문입니다. 모든 호출을 삭제 작업과 같은 수준으로 신중하게 다루세요.
접근 수준: 파괴적
파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
action | string | 예 | 일괄 작업: add(접근 권한 부여) 또는 remove(접근 권한 회수) |
server_ids | array | 예 | 접근 권한을 추가·제거할 서버 UUID(1~100개) |
api_token_id | string | 조건부 | 대상 API 토큰(service_token_id와 상호 배타적, 둘 중 하나 필수) |
service_token_id | string | 조건부 | 대상 서비스 토큰(api_token_id와 상호 배타적, 둘 중 하나 필수) |
예시
“모니터링 토큰에게 스테이징 플릿의 모든 서버 접근 권한을 줘”
에이전트는 action="add", server_ids를 스테이징 플릿의 UUID로, api_token_id를 모니터링 토큰의 ID로 설정해 bulk_server_acl을 호출합니다.
파일 ACL
파일 ACL 규칙은 토큰이 WebFTP로 업로드·다운로드할 수 있는 파일 경로를 제어합니다. 각 규칙은 정확히 하나의 토큰에 연결되며, 업로드·다운로드 또는 둘 다로 동작을 제한할 수 있습니다.
list_file_acls
워크스페이스에 설정된 파일 ACL 규칙을 조회합니다. api_token_id나 service_token_id로 필터링하면 특정 토큰의 규칙만 볼 수 있습니다(둘 다 지정하면 오류가 발생합니다).
접근 수준: 읽기 전용
파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
api_token_id | string | 아니오 | API 토큰 ID로 필터링(service_token_id와 상호 배타적) |
service_token_id | string | 아니오 | 서비스 토큰 ID로 필터링(api_token_id와 상호 배타적) |
page | integer | 아니오 | 페이지네이션 페이지 번호 |
page_size | integer | 아니오 | 페이지당 항목 수 |
예시
“백업 서비스 토큰이
/var/log에서 다운로드할 수 있어?”
에이전트는 service_token_id를 백업 토큰의 ID로 설정해 list_file_acls를 호출하고, 해당 경로의 download를 허용하는 규칙이 있는지 확인합니다.
create_file_acl
/etc/nginx/*나 /var/log/*.log 같은 경로 패턴에 대한 업로드·다운로드 권한을 제어하는 파일 ACL 규칙을 생성합니다. api_token_id나 service_token_id 중 정확히 하나를 지정해야 합니다.
접근 수준: 추가적
파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
path | string | 예 | 매칭할 파일 경로 패턴(예: /etc/nginx/*, /var/log/*.log). * 와일드카드 지원 |
action | string | 예 | 허용할 동작: upload, download, 또는 *(둘 다) |
api_token_id | string | 조건부 | 이 규칙이 적용될 API 토큰(service_token_id와 상호 배타적, 둘 중 하나 필수) |
service_token_id | string | 조건부 | 이 규칙이 적용될 서비스 토큰(api_token_id와 상호 배타적, 둘 중 하나 필수) |
username | string | 아니오 | 시스템 사용자명 제한. 비워두면(기본값) 토큰 소유자로만 제한되고, *는 모든 사용자를 허용 |
groupname | string | 아니오 | 시스템 그룹명 제한. 비워두면(기본값) 제한이 없음 |
예시
“백업 서비스 토큰이
/var/log아래 모든 것을 다운로드할 수 있게 해줘”
에이전트는 path="/var/log/*", action="download", service_token_id를 백업 토큰의 ID로 설정해 create_file_acl을 호출합니다.
update_file_acl
기존 파일 ACL 규칙의 경로, 동작, 또는 사용자명·그룹명 제한을 수정합니다. 이 규칙의 토큰 연결은 여기서 바꿀 수 없으며, 다른 토큰에 연결하려면 규칙을 삭제하고 다시 생성해야 합니다.
접근 수준: 멱등적 쓰기
파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
acl_id | string | 예 | 수정할 파일 ACL 규칙 ID |
path | string | 아니오 | 새 파일 경로 패턴 |
action | string | 아니오 | 새로 허용할 동작: upload, download, 또는 * |
username | string | 아니오 | 시스템 사용자명 제한. 기존 제한을 지우려면 ''를 명시적으로 전달하고, 변경하지 않으려면 생략 |
groupname | string | 아니오 | 시스템 그룹명 제한. 기존 제한을 지우려면 ''를 명시적으로 전달하고, 변경하지 않으려면 생략 |
예시
“그 토큰이 다운로드뿐 아니라
/etc/nginx에 업로드도 할 수 있게 해줘”
에이전트는 list_file_acls로 규칙을 찾은 뒤, 그 규칙의 acl_id와 action="*"로 update_file_acl을 호출합니다.
delete_file_acl
파일 ACL 규칙을 영구적으로 삭제합니다. 되돌릴 수 없으며, 토큰은 즉시 그 규칙이 부여한 파일 접근 권한을 잃습니다.
접근 수준: 파괴적
파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
acl_id | string | 예 | 삭제할 파일 ACL 규칙 ID |
예시
“외부 계약자 토큰의
/etc업로드 권한을 회수해줘”
에이전트는 list_file_acls로 일치하는 규칙을 찾아 사용자에게 확인받은 뒤, 그 규칙의 acl_id로 delete_file_acl을 호출합니다.
승인 요청
승인 요청은 작업을 진행하기 전에 사람의 승인이 필요할 때 나타납니다. 예를 들어 작업 세션의 sudo 정책에 막힌 sudo 명령이나, 활성화되기 전 승인 대기 상태인 작업 세션이 있습니다. 이 도구들은 에이전트가 승인 요청을 조회하고 절차를 설명할 수 있게 하지만, 결정을 내리지는 못합니다.
approve_request나 reject_request 같은 도구는 의도적으로 존재하지 않습니다. 요청을 승인하거나 거부하는 결정은 항상 Alpacon 웹 콘솔(설정된 경우 Slack)에서 사람이 내리며, MCP를 통해서도 AI 에이전트 스스로도 할 수 없습니다. 대기 중인 요청을 조회하려면 list_approval_requests와 get_approval_request를 사용하고, 사람에게 전달할 안내가 필요하면 explain_approval_decision을 사용하세요.
list_approval_requests
워크스페이스의 대기 중·과거 승인 요청을 요청 유형, 상태, 요청자와 함께 조회합니다. 결정을 기다리는 항목을 검토하거나 승인 이력을 확인할 때 사용합니다.
접근 수준: 읽기 전용
파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
status | string | 아니오 | 상태로 필터링: pending, approved, rejected, cancelled, expired |
page | integer | 아니오 | 페이지네이션 페이지 번호 |
page_size | integer | 아니오 | 페이지당 항목 수 |
예시
“이 워크스페이스에서 아직 승인 대기 중인 게 뭐야?”
에이전트는 status="pending"으로 list_approval_requests를 호출하고 결과를 사용자에게 요약해줍니다.
get_approval_request
승인 요청 하나의 상세 정보(요청자, 요청 유형, 사유, 상태, 타임스탬프)를 조회합니다.
접근 수준: 읽기 전용
파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
request_id | string | 예 | 조회할 승인 요청 ID |
예시
“승인 요청
a1b2c3d4는 누가 왜 요청한 거야?”
에이전트는 request_id="a1b2c3d4"로 get_approval_request를 호출하고 요청자와 사유를 사용자에게 보고합니다.
explain_approval_decision
승인·거부가 사람만 할 수 있는, MCP 밖에서 일어나는 작업임을 설명합니다. 이 도구는 아무것도 변경하지 않고 Alpacon API도 호출하지 않습니다. AI 에이전트가 스스로 승인자가 되어서는 안 되기 때문입니다. 에이전트가 스스로 승인을 시도하는 대신 요청을 사람에게 전달하고 기다리도록, 구조화된 안내를 반환합니다. list_approval_requests나 get_approval_request 다음에 호출하거나, 도구 호출이 승인 대기 결과를 반환한 직후(예: execute_command의 SUDO_APPROVAL_REQUIRED 거부, 또는 pending 상태로 생성된 작업 세션)에 호출하세요.
접근 수준: 읽기 전용
파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
request_id | string | 아니오 | 이 안내가 참조하는 승인 요청 ID |
예시
“내 명령이 sudo 승인이 필요해서 거부됐어, 어떻게 해야 해?”
에이전트는 explain_approval_decision을 호출해 안내를 전달합니다. 대기 중인 요청을 사람에게 전달하고, 그 사람이 Alpacon 웹 콘솔에서 검토·결정한 뒤 승인되면 명령을 다시 시도하라는 내용입니다.
sudo 정책
sudo 정책은 어떤 사용자나 그룹이 어떤 서버에서 어떤 명령을 상위 권한으로 실행할 수 있는지, 비밀번호가 필요한지를 정의합니다. execute_command 중 sudo 정책에 막힌 명령은 단순 거부가 아니라 승인 대기 결과로 나타납니다.
list_sudo_policies
워크스페이스에 설정된 sudo 정책을 조회합니다. 정책 이름, 허용된 명령, 할당된 사용자·서버, 유효 기간이 포함됩니다. 워크스페이스에 어떤 sudo 권한이 설정되어 있는지 감사할 때 사용합니다.
접근 수준: 읽기 전용
파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
page | integer | 아니오 | 페이지네이션 페이지 번호 |
page_size | integer | 아니오 | 페이지당 항목 수 |
예시
“프로덕션 서버에 적용되는 sudo 정책은 뭐야?”
에이전트는 list_sudo_policies를 호출하고 각 정책의 servers와 commands 필드에서 일치하는 항목을 검토합니다.
create_sudo_policy
특정 사용자나 그룹이 어떤 서버에서 상위 권한으로 실행할 수 있는 명령을 정의하는 sudo 정책을 생성합니다. users, groups, servers를 비워두면 해당 항목은 전체에 적용됩니다. 슈퍼유저 권한이 필요합니다.
접근 수준: 추가적
파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
name | string | 예 | sudo 정책의 이름 |
commands | array | 예 | 이 정책이 허용하는 명령 |
users | array | 아니오 | 정책이 적용될 사용자 ID. 비워두거나 생략하면 모든 사용자 |
groups | array | 아니오 | 정책이 적용될 그룹 ID. 비워두거나 생략하면 모든 그룹 |
servers | array | 아니오 | 정책이 적용될 서버 ID. 비워두거나 생략하면 모든 서버 |
run_as | string | 아니오 | 명령을 실행할 사용자 |
no_password | boolean | 아니오 | 비밀번호 없는 sudo 허용 여부(기본값: false) |
description | string | 아니오 | sudo 정책 설명 |
예시
“ops 그룹이 웹 플릿에서 비밀번호 없이
systemctl restart *를 sudo로 실행하게 해줘”
에이전트는 name="ops-restart", commands=["systemctl restart *"], groups를 ops 그룹의 ID로, servers를 웹 플릿의 UUID로, no_password=true로 설정해 create_sudo_policy를 호출합니다.
관련 문서
- 명령 실행 도구: 이 명령 ACL 규칙과 sudo 정책의 통제를 받는 명령을 실행합니다
- 작업 세션: 명령 실행과 파일 전송이 그 안에서 이루어지는 승인 대기 세션입니다
- IAM·API 토큰 도구: ACL 규칙과 sudo 정책이 참조하는 사용자, 그룹, 토큰을 관리합니다