# 보안 주의사항

Ante를 안전하게 운영하기 위해 알아야 할 보안 원칙과 설정을 안내합니다.

> [!WARNING]
> Ante는 실제 자금을 다루는 시스템입니다. 이 문서의 내용을 충분히 숙지한 뒤 운영하세요.

---

## 🌐 네트워크 보안은 사용자 책임입니다

Ante는 개인 홈서버 위에서 구동되는 것을 전제로 설계되었습니다. 시스템 자체에는 방화벽, TLS 종료, DDoS 방어 같은 네트워크 보안 기능이 포함되어 있지 않습니다. 외부 브로커 연결, Telegram 알림, SSH/원격 접속 같은 운영 네트워크 표면은 사용자가 직접 보호해야 합니다.

외부에서 홈서버에 접근해야 한다면 다음을 직접 구성해야 합니다:

- **SSH 보안** — 공개키 인증, 제한된 사용자, 필요 시 VPN 또는 Tailscale 같은 사설망을 사용합니다.
- **방화벽** — 필요한 포트만 허용하고, 브로커/알림 외 불필요한 inbound를 닫습니다.
- **비밀값 관리** — API 키와 토큰은 `secrets.env` 또는 환경변수로만 보관합니다.

---

## 🤖 에이전트 신뢰 모델

Ante의 권한 체계는 **선한 에이전트를 전제**로 설계되어 있습니다. 이것이 의미하는 바를 정확히 이해해야 합니다.

### 방어가 작동하는 경우

Ante는 에이전트가 자신에게 부여된 scope를 넘어서 실수로 잘못된 API를 호출하는 상황을 방어합니다. `strategy:write` scope만 가진 에이전트가 봇을 생성하거나 시스템 설정을 변경하려 하면 요청이 거부되고 감사 로그에 기록됩니다.

- 토큰은 SHA-256 해시로만 저장되어 DB가 유출되어도 토큰 원문을 복원할 수 없습니다.
- `ante_hk_`(사용자)와 `ante_ak_`(에이전트) 토큰이 물리적으로 분리되어 있어, 에이전트 토큰이 탈취되어도 사용자 권한으로 상승할 수 없습니다.
- 모든 API 호출은 멤버 ID, 액션, IP 주소와 함께 감사 로그에 기록됩니다.

### 방어가 작동하지 않는 경우

에이전트가 부여받은 scope 범위 *안에서* 의도적으로 악의적인 행동을 하는 경우, 시스템이 이를 자동으로 차단하지는 않습니다. 예를 들어:

- `strategy:write` scope를 가진 에이전트가 손실을 유발하는 전략을 의도적으로 제출
- `bot:admin` scope를 가진 에이전트가 정상 봇을 임의로 정지
- `data:write` scope를 가진 에이전트가 조작된 데이터를 주입하여 백테스트 결과를 왜곡

이런 행위는 권한 체계상 정당한 요청이므로 scope 검증만으로는 막을 수 없습니다. 따라서 다음 원칙을 지켜야 합니다:

1. **최소 권한 원칙** — 에이전트에게 역할 수행에 필요한 scope만 부여합니다. "일단 넓게"는 위험합니다.
2. **감사 로그 확인** — `ante audit list`로 에이전트의 활동 이력을 정기적으로 확인합니다.
3. **즉시 차단** — 이상 행동이 발견되면 `ante member suspend <MEMBER_ID>`로 즉시 정지합니다.
4. **토큰 위생** — 토큰을 코드에 하드코딩하지 말고 환경변수로 관리하며, 90일 만료 전에 `rotate-token`으로 갱신합니다.

---

## 🛑 계좌별 Kill Switch

Ante는 계좌 단위로 거래를 중단하고 재개할 수 있습니다. 이상 상황이 감지되면 해당 계좌만 정지하여, 다른 계좌의 거래에 영향을 주지 않습니다.

```bash
# 특정 계좌 즉시 정지
ante account suspend domestic

# 정지된 계좌 재활성화
ante account activate domestic
```

계좌가 정지(SUSPENDED)되면 해당 계좌에 연결된 모든 봇의 주문이 차단됩니다. 이미 접수된 주문은 영향을 받지 않지만, 새 주문은 계좌가 다시 활성화될 때까지 거부됩니다.

시스템 전체를 긴급 중단해야 할 때는 `ante system halt` 명령어로 모든 계좌를 일괄 정지할 수 있습니다.

---

## 🔑 민감 정보 관리

| 항목 | 저장 위치 | 비고 |
|------|----------|------|
| KIS API Key / Secret | `accounts` 테이블 (`credentials` 컬럼) | 계좌별 DB 저장 |
| 텔레그램 Bot Token | `~/.config/ante/secrets.env` | `.gitignore` 대상 |
| 멤버 토큰 | 환경변수 `ANTE_MEMBER_TOKEN` | DB에는 해시만 저장 |
| Recovery Key | 사용자가 직접 보관 | 시스템에 원문 저장 안 함 |
| DB 파일 | `~/.config/ante/db/` | 거래 기록, 감사 로그, 계좌 인증 정보 포함 |

증권사 API 인증 정보(app_key, app_secret, account_no)는 계좌 생성 시 `accounts` 테이블의 `credentials` 컬럼에 저장됩니다. 인증 정보를 확인하거나 변경하려면:

```bash
# 인증 정보 확인 (마스킹 출력)
ante account credentials domestic

# 인증 정보 변경 (비대화형, cold-path 전용)
# 환경변수 채널 (권장)
ante account set-credentials domestic \
  --credential-env app_key=ANTE_KIS_APP_KEY \
  --credential-env app_secret=ANTE_KIS_APP_SECRET \
  --credential-env account_no=ANTE_KIS_ACCOUNT_NO

# 또는 파일 채널 (Docker secret 등)
ante account set-credentials domestic \
  --credential-file app_key=/etc/ante/secrets/app_key \
  --credential-file app_secret=/etc/ante/secrets/app_secret \
  --credential-file account_no=/etc/ante/secrets/account_no
```

> `BrokerPreset.required_credentials`의 모든 키를 한 번에 제공해야 하며, 부분 갱신은 허용되지 않습니다. 채널 셋(`--credential` / `--credential-env` / `--credential-file`)이 모두 비어 있으면 `ACCOUNT_MISSING_REQUIRED_CREDENTIAL` 에러로 실패합니다.

`secrets.env`와 DB 디렉토리는 해당 서버의 파일 시스템 권한으로 보호해야 합니다:

```bash
chmod 600 ~/.config/ante/secrets.env
chmod 700 ~/.config/ante/db
```
