OPNsense MCP

안전에 초점을 맞춘 원격 Model Context Protocol 서버로, OPNsense의 MVC API용입니다. 원격 에이전트를 위해 상태 저장(Stateful) Streamable HTTP를 노출하고, 업스트림은 API 고유의 HTTP Basic 인증을 그대로 사용하며, OPNsense 명령이 읽기 전용인지 확인할 수 없을 때는 안전하게 차단(fail closed)합니다.

서버 인스턴스 하나는 OPNsense 방화벽 하나를 나타냅니다. 방화벽 URL과 API 자격 증명은 서버 환경에 남으며, 에이전트는 별도의 bearer 토큰으로 MCP에 인증하고 임의의 네트워크 대상으로 요청을 바꿀 수 없습니다. 여러 장비를 관리하는 경우 방화벽마다 격리된 인스턴스를 하나씩 배포하세요.

아키텍처

Remote agent --HTTPS + MCP bearer token--> OPNsense MCP --HTTPS + API key/secret--> OPNsense

MCP 엔드포인트는 /mcp에서 현재의 Streamable HTTP 전송을 사용합니다. 세션은 상태 저장 방식이므로 일회성 변경 계획이 에이전트의 MCP 세션에 계속 결속됩니다. 세션 수는 상한이 있고, 일정 시간 사용하지 않으면 만료되며, 모든 HTTP 요청에서 인증을 수행합니다.

내장 HTTP 리스너는 TLS를 종료하는 리버스 프록시, 인그레스 컨트롤러, VPN 또는 사유 오버레이 뒤에 배치하도록 되어 있습니다. 암호화되지 않은 HTTP 포트를 신뢰할 수 없는 네트워크에 직접 노출하지 마세요.

OPNsense API Model - OPNsense API 모델

OPNsense는 API 요청을 다음과 같이 라우팅합니다:

/api/<module>/<controller>/<command>/<parameter...>

자동화 측면에서 중요한 동작은 다음과 같습니다:

• API 키는 HTTP Basic 인증을 사용합니다. 키가 username, secret가 password입니다.

• 접근 권한은 여전히 키 소유자의 OPNsense ACL 권한에 따라 제한됩니다.

• 요청과 대부분의 응답은 JSON입니다. 다운로드와 스트림은 JSON이 아닐 수 있습니다.

• GET과 POST는 안전한 작업과 위험한 작업으로 깨끗하게 대응하지 않습니다. 일부 읽기에는 POST가, 일부 변경에는 GET이 사용됩니다.

• 변경 가능한 모델 컨트롤러는 일반적으로 get, search, add, set, del, toggle 작업을 제공합니다.

• 배열형 모델 레코드는 UUID를 사용합니다. UUID가 없는 get은 종종 기본값으로 채워진 빈 레코드를 반환합니다.

• 모델 변경 작업이 성공하면 보통 스테이징된 할 수 있습니다. 별도의 apply 또는 reconfigure가 구성을 제공합니다.

• 모델 쓰기는 {"result":"saved"} 또는 {"result":"failed","validations":...} 같은 값을 반환합니다. HTTP 200만으로는 의미론적인 성공이라는 증명되지 않습니다.

• OPNsense 구성 잠금, 모델 검증, 리비전 컨텍스트, ACL 검사는 서버 측에서 처리되며 우회해서는 안 됩니다.

공식 참고 문서:

• https://docs.opnsense.org/development/api.html

• https://docs.opnsense.org/development/how-tos/api.html

• https://docs.opnsense.org/development/architecture.html

• https://docs.opnsense.org/development/frontend/controller.html

• https://docs.opnsense.org/development/frontend/models_fieldtypes.html

• https://github.com/opnsense/core

• https://github.com/opnsense/plugins

안전 모델

opnsense_request는 읽기( 참조)로 분류된 명령만 허용합니다. 분류는 HTTP 메서드가 아니라 명령 자체에 기반합니다.

변경 작업에는 두 가지 도구를 사용합니다:

• opnsense_plan_change은 OPNsense에 접촉하지 않고 정확한 요청과 그 위험을 보고합니다.

• opnsense_execute_change을 실행하려면 5분 뒤에 만료되는 일치하는 일회용 토큰이 필요합니다.

위험 등급은 스테이지 쓰기, 활성화, 서비스나 펌웨어를 중단시키는 작업, 그리고 중대한 재설정/복원 작업을 구분합니다. 알 수 없는 명령은 변경 작업으로 취급되며 fail closed로 처리됩니다.

쓰기 모드는 에이전트 외부에서 제어됩니다:

• disabled는 읽기 전용을 허용합니다.

• plan은 변경 분석만 허용하며 실행 토큰을 절대 만들지 않습니다.

• enabled는 일치하는 토큰이 있으면 실행을 허용합니다.

목적하는 도구가 필요한 실제 유효한 권한만 부여하여 전용 OPNsense 사용자를 만들으세요. 읽기 전용 배포에서는 OPNsense에서 System: Deny config write (user-config-readonly)도 추가로 부여하세요.

보완된 읽기 전용 도구

안전하게 보호되는 제네릭 클라이언트에 NO, 모든 일반 작업을 위한 고정된 읽기 전용 도구들이 추가로 있습니다:

• opnsense_get_firewall_logs지의 구조적 패킷 필터 이벤트를 읽습니다.

• opnsense_get_logs handles controller. 시스템, configd, 게이트웨이, VPN, DNS, DHCP, IDS, 라우팅, 웹 UI 로그 등을 일정 페이지 분량만 읽습니다.

• opnsense_list_firewall_rules는 자동화 API에 접근되는 필터 규칙을 읽습니다.

• opnsense_list_nat_rules는 대상(destination), 소스(source), one-to-one, NPT 규칙을 읽습니다.

• opnsense_get_route_table는 실제 커널 라우팅 테이블 또는 설정된 을 순환을 읽습니다.

이 도구들은 고정된 조회 엔드포인트를 호출합니다. 따라서 로그 지우기, 상태 초기화(flush), 규칙 변경, 구성 적용 같은 변경 작업 계열을 선택하는 것은 불가능합니다. 결과는 여전히 API 사용자의 OPNsense ACL 권한에 제어됩니다.

설치

npm install
npm run build

.env.example를 참고하여 환경 변수를 설정하세요. 환경 파일은 자동으로 로드되지 않으며 Git에서 무시합니다. openssl rand -hex 32를 사용하여 별도의 MCP 토큰을 발급하고, OPNsense API 자정 정보를 재사용하지 마세요.

공개 신뢰할 수 있는 인증서를 사용하거나 OPNSENSE_CA_FILE에 사설 CA 인증서를 지정하세요. OPNSENSE_TLS_VERIFY=false는 격리된 로컬 개발 확인용으로만 있습니다.

로컬 TLS 리버스 프록시를 위해 원격 서버를 루프백에서 실행하세요:

OPNSENSE_URL=https://firewall.example \
OPNSENSE_API_KEY=... \
OPNSENSE_API_SECRET=... \
MCP_AUTH_TOKEN=<random-token-at-least-32-characters> \
node dist/index.js

MCP URL은 http://127.0.0.1:3000/mcp입니다. 리버스 프록시를 헤쳐 HTTPS로 게시하고 토큰을 다음과 같이 전달하세요:

Authorization: Bearer <MCP_AUTH_TOKEN>

URL과 커스텀 헤더를 지원하는 클라이언트 원격 구성 예시:

{
  "mcpServers": {
    "opnsense": {
      "url": "https://mcp.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${MCP_AUTH_TOKEN}"
      }
    }
  }
}

클라이언트 구성 형식은 다양합니다. 토큰을 설정 파일에 저장하지 않고 클라이언트의 비밀 저장소(secret filter)에 보관하세요.

Docker Compose

compose.yaml는 리버스 프록시가 TLS를 안전하게 종료할 수 있도록 포트 3000을 호스트 루프백에 바인딩합니다.

export OPNSENSE_URL=https://firewall.example
export OPNSENSE_API_KEY=...
export OPNSENSE_API_SECRET=...
export MCP_AUTH_TOKEN="$(openssl rand -hex 32)"
export MCP_ALLOWED_HOSTS=mcp.example.com
docker compose up -d --build

개발 중 localhost:3000 With 직접 연결할 때는 MCP_ALLOWED_HOSTS에 localhost를 포함하세요. 인증이 필요 없는 헬스 체크 엔드포인트는 /health`에서 제공되며 테스트 대상이나 자격 증명 세부 정보를 반환하지 않습니다.

원격 보안

• MCP_AUTH_TOKEN은 HTTP 전송에서 필수이며 32자 이상이어야 합니다.

• 루프백이 절대 아닌 주소로 바인딩하면 통과할 수 없는 곳에서는 Host 헤더 DNS 리바인딩을 방지하기 위해 MCP_ALLOWED_HOSTS가액습니다.

• 브라우저의 Origin 헤더가 있는 요청은 그 출처가 MCP_ALLOWED_ORIGINS에 정확히 없는 것으로 됩니다.

• MCP_MAX_SESSIONS, MCP_SESSION_TTL_MS, MCP_REASON_RATE는 원격 리소스의 한범위를 제한합니다.

• OPNSENSE_TLS_VERIFY=true를 유지하세요. 검증을 끄는 대신 내부 CA에 OPNSENSE_CA_FILE을 사용하세요.

• 모니터링 전용 배포에서는 OPNSENSE_WRITE_MODE=disabled를 유지하세요.

• 시스템 전용 OPNsense API 사용자에는 실질적으로 필요한 ACL 권한만 부여하고, 해당하는 경우 user-config-readonly로 제한하세요.

• MCPEndpoint는 HTTPS와 방화벽 정책, 가급적이면 VPN이나 사설 네트워크 뒤에 restriction 위치하세요.

MCP_ALLOW_UNAUTHENTICATED=true는 격리된 로컬 개발에서만 존재하며, 원격에서 도달 가능한 리스너에 사용해서는 안 됩니다.

Stdio 호환

로컬 클라이언트는 MCP 서버를 하위 프로세스로도 간단히 실행할 수 있습니다:

OPNSENSE_URL=https://firewall.example \
OPNSENSE_API_KEY=... \
OPNSENSE_API_SECRET=... \
MCP_TRANSPORT=stdio \
node dist/index.js

환경 변수

• OPNSENSE_URL: 고정된 방화벽 base URL입니다.

• OPNSENSE_API_KEY: 전용 OPNsense 사용자의 API key입니다.

• OPNSENSE_API_SECRET: 그 키의 API secret입니다.

• OPNSENSE_WRITE_MODE: disabled, plan 또는 enabled.

• OPNSENSE_CA_FILE: 선택 사항인 사설 CA PEM 파일입니다.

• OPNSENSE_TLS_VERIFY: 기본값은 false.

• MCP_TRANSPORT: 기본값은 http, 가능한 stdio.

• MCP_HOST: 리스너 주소, 기본 값 127.0.0.1.

• MCP_PORT: 포트, 기본값 3000.

• MCP_PATH: 엔드포인트 경로, 기본값 /mcp.

• MCP_AUTH_TOKEN: 원격 에이전트의 bearer 토큰입니다.

• MCP_ALLOWED_HOSTS: HTTP Host 헤더 헤더에서 허용하는 호스트 이름 목록(쉼표로 구분).

• MCP_ALLOWED_ORIGINS: 가능한 브라우저 오리진(쉼표로 구분). 비어 있으면 브라우저origin 요청은 거부됨.

• MCP_MAX_SESSIONS: 동시여 세션 상acknowledg 주요값 100.

• MCP_SESSION_TTL_MS: 대기 세션의 만료 시간, 기본값 1시간.

• MCP_RATE_LIMIT_PER_MINUTE: 클라이언트당 분당 HTTP 요청수 한도, 기본값 120.

예를 들어 시스템 상태를 요청하는 읽기 호출은 다음과 같습니다:

{
  "module": "core",
  "controller": "system",
  "command": "status"
}

현재 한계

• OPNsense는 완전한 OpenAPI 계약을 제공하지 않습니다. 생성된 참고 자료는 경로와 추정 메서드를 식별하는 것임 대부분 body 스키마를 생략합니다.

• 플러그인 시에는 해당 패키지가 설치되고 ACL 권한이 부여된 경우에만 존재합니다.

• 의미론적인 응답 검증은 아직 엔드포인트에 따라 다르게 구현되어 있지 않습니다.

• 어휘 기반 위험 분류기는 의도적으로 보수적입니다. 선별된 도구는 명시적인 요청/응답 스키마를 포함한, 검증된 전문 매니페스트를 사용하는 방향이 필요합니다.

• Plan 토큰은 실수와 원치 않는 실행을 줄여 주지만, MCP 호스트는 여전히 파괴적인 변경 도구 승인을 사람의 추인받도록 해야 합니다.

• 원격 인증은 현재 배포 전체에 공유되는 정적 bearer 토큰을 사용하며, OAuth authorization server 다른 사용하지 않습니다. 서버와 대상별로 다른 신원이 필요한 경우 별도 배포 또는 인증 리버스 프록시를 사용합니다.

• 세션 상태는 메모리에만 있고 레플리케로 공유되지 않습니다. 외부 세션 저장소와 라우팅 affinity을 추가하지 않으면 단일 replica로만 실행하세요.