backbay-labs/hushAI 에이전트의 행동 경계를 위한 이식 가능한 보안 규칙
에이전트에게 읽을 수 있는 경계를 부여하세요. 검증할 수 있는 결정을 얻으세요.
개요 · 빠른 시작 · 작동 방식 · SDK · CLI · 정책 · 문서 · 명세
HushSpec은 AI 에이전트가 작동하는 보안 제어에 대한 공개 명세입니다. YAML로 정책을 작성하고 Rust, TypeScript, Python 또는 Go로 평가하여 각 결정을 그 뒤에 있는 정책과 연결하는 영수증을 생성하세요.
에이전트가 실제로 다루는 것들—파일, 네트워크, 셸, 도구, 브라우저,
코드 실행—을 다룹니다. 명세는 규칙과 그 의미를 정의하며, 런타임은
HushGuard 또는 자체 통합을 통해 경계를 시행합니다.
| 선언 | 시행 | 증명 |
|---|---|---|
| 재사용 가능한 기본 정책과 명시적 권한을 갖춘 검토 가능한 YAML. | 작업 시점에서 일관된 allow, warn, deny 결정. | 결정 영수증, 정책 서명, 검증 가능한 로그. |
명세 1.0.0은 안정적입니다. 문서 형식, 평가 의미론, 정규 형식, 그리고 전송 형식은 1.x 시리즈 동안 고정됩니다. 계약과 테스트 커버리지에 대해서는 버전 관리 정책과 SDK 적합성 매트릭스를 참조하세요.
1.0 SDK 릴리스는 아직 게시되지 않았습니다. 구현, 검증, 릴리스 증거에 대해서는 전달 상태를 참조하세요.
실험적인 외부 적합성 컨트롤러는 캡처된 실행 파일을 L0-L3 코퍼스에 대해 테스트하고 그 입력, 출력, 정체성을 보존합니다. Go 어댑터는 자사 브링업이며, 독립적인 엔진이나 런타임 경계 검증이 아닙니다.
실험적인 신뢰할 수 있는 호출 코디네이터는 호스트가 검증한 MCP 도구와 그 효과를 하나의 인증된 정책 스냅샷에 대해 확인하고, 지속적인 허가를 기록한 후 디스패치합니다. 격리된 코딩 파일럿은 실제 편집, 차단된 작업, 충돌 증거를 테스트합니다. 이는 범위가 한정된 자사 데모이며, 외부 채택이나 일반적인 MCP 격리가 아닙니다.
이 체크아웃에서 h2h CLI를 빌드하세요:
cargo install --path crates/hushspec-cli --locked
다음을 policy.yaml로 저장하세요. 자격 증명을 보호하고, 네트워크 접근을 제한하며,
도구가 파일을 쓰거나 코드를 푸시하기 전에 확인을 요청합니다.
hushspec: "1.0.0"
name: production-agent
rules:
forbidden_paths:
patterns: ["**/.ssh/**", "**/.aws/**", "/etc/shadow"]
egress:
allow: ["api.openai.com", "*.anthropic.com", "api.github.com"]
default: block
tool_access:
allow: [file_read, search]
block: [shell_exec, run_command]
require_confirmation: [file_write, git_push]
default: block
검증한 다음 세 가지 결정을 시도해 보세요:
h2h validate policy.yaml
h2h eval policy.yaml --type egress --target api.openai.com
# allow
h2h eval policy.yaml --type tool_call --target shell_exec
# deny
h2h eval policy.yaml --type tool_call --target file_write
# warn: confirmation required
이 명령들은 작업을 평가하며, 실행하지는 않습니다. eval은 allow의 경우 0,
deny의 경우 1, warn의 경우 4로 종료됩니다. 런타임은 작업을 디스패치하기 전에
결정을 처리해야 합니다. 에이전트에 연결하기 →
| 방법 | 설치 |
|---|---|
| Cargo | cargo install hushspec-cli |
| Homebrew | brew install backbay-labs/tap/h2h |
| npm | npm install -g @hushspec/cli |
| 사전 빌드된 바이너리 | GitHub Releases, 체크섬 및 출처 증명 포함 |
패키지된 설치 프로그램은 릴리스 파이프라인이 해당 아티팩트를 게시했는지에 따라 달라집니다. 위의 소스 설치는 이 체크아웃에서 직접 빌드합니다.
스캐폴딩된 정책과 테스트 스위트를 원하시면 h2h init --preset default를 실행하세요.
전체 워크플로우는 첫 정책 가이드를 참조하세요.
HushGuard는 정책을 로드하고 평가, 시행 모드, 확인, 영수증 싱크, 옵저버를
함께 가져옵니다. 도구를 디스패치하기 전에 enforce를 호출하세요:
import { HushGuard } from '@hushspec/core';
const guard = HushGuard.fromFile('./policy.yaml');
guard.enforce({ type: 'tool_call', target: 'shell_exec' });
// Throws HushSpecDenied under the quickstart policy.
필수 서명 검증에 실패한 정책은 거부된 가드를 생성합니다:
모든 작업이 __hushspec_policy_unverified__로 거부됩니다. 핫 리로드 실패 시
마지막 유효한 정책이 계속 적용됩니다. 알 수 없는 필드와 유효하지 않은 문서는
명시적으로 거부됩니다.
시행 경계는 런타임의 책임입니다. HushSpec은 이식 가능한 정책 계약과 이를 구축하기 위한 SDK 프리미티브를 제공합니다. 런타임 통합 가이드 →
감사된 평가는 해석된 정책을 받아 정규 content_hash, 결정, 행위자 컨텍스트,
규칙 및 탐지 추적, 시행 처분을 포함하는 영수증을 반환합니다. 작업 내용은
원시 콘텐츠를 포함하지 않고 해시와 바이트 크기로 표현됩니다.
# Inspect the receipt for one evaluated action.
h2h eval policy.yaml --type egress --target api.openai.com --format receipt
증거는 런타임을 넘어 이동할 수 있습니다:
| 아티팩트 | 검증할 수 있는 것 |
|---|---|
| 정책 서명 | 상속된 규칙을 포함하여 해석된 정책에 서명한 키. |
| 결정 영수증 | 어떤 정책과 기록된 규칙 결과가 결정을 생성했는지. |
| 영수증 로그 | 항목 간 해시 링크, 첫 번째 깨진 링크는 줄로 식별됨. |
| 정책 번들 | 정책을 설명하는 in-toto 명세서에 대한 DSSE 증명. |
Ed25519 서명은 해석된 정책의 콘텐츠 해시를 커버하므로, 파일을 재포맷해도
서명이 유지되지만 상속된 규칙을 변경하면 무효화됩니다. 서명, 영수증 검증,
번들 검증은 네 가지 SDK 모두에서 사용할 수 있습니다; Rust는 signing 기능이,
Python은 signing 추가 기능이 필요합니다.
네 가지 SDK에 걸친 하나의 정책 언어. 공유 코퍼스는 구현 전반에 걸쳐 평가, 정규 바이트, 정책 해시, 영수증 형식을 검사합니다.
1.0이 게시될 때까지 이 소스 체크아웃을 사용하세요. 아래의 레지스트리 명령은 다가오는 릴리스용이며, 현재 사용 가능한 1.0 패키지가 아닙니다.
| SDK | 게시 후 레지스트리 설치 | 참조 |
|---|---|---|
| Rust | cargo add hushspec | Crate |
| TypeScript | npm install @hushspec/core | Package |
| Python | pip install hushspec | Package |
| Go | go get github.com/backbay-labs/hush/packages/[email protected] | Module |
Go SDK 릴리스는 중첩된 packages/go/v1.0.0 태그를 사용할 것입니다.
서명의 경우 Rust에서는 hushspec = { version = "1.0", features = ["signing"] }을,
Python에서는 pip install "hushspec[signing]"을 사용하세요.
use hushspec::HushSpec;