OPNsense MCP

방화벽에 대해 일상 언어로 질문하세요.

OPNsense용 읽기 전용 도구 4개 — 기본적으로 읽기 전용이며, 검증한 내용에 대해서만 구체적으로 답합니다.

빠른 시작 · 도구 · 설정 가이드 · 검증 · 상태

미리 보기: AI 어시스턴트가 OPNsense 시스템을 검사할 수 있게 해주는 소형 MCP 서버로, 명시적으로 활성화된 경우에만 확인, 백업, 감사 봉투(audit envelope)를 거쳐 한 종류의 방화벽 별칭(alias)을 생성하거나 삭제할 수 있습니다. 기본적으로 읽기 전용입니다. 패키징된 서버는 합성 HTTPS 대상과 일회용 OPNsense 26 VM 양쪽에서 테스트됩니다.

일상 언어로 질문하세요. 서버는 에이전트에게 사실부터 시작하고, 네트워킹 용어를 설명하고, 한 번에 하나의 유용한 명확화 질문을 하며, 관찰과 가설을 명확히 구분하도록 지시합니다.

빠른 시작

읽기 전용, 약 15분 소요. macOS 또는 Linux에서 Node.js 22.19 이상(22 메이저 버전 내)이 필요합니다.

1. 방화벽 자격 증명 저장

npx -y @gabrielion/opnsense-mcp configure

HTTPS 오리진(origin), API 키와 시크릿, 선택적 CA 파일을 요청합니다. 아무것도 에코되지 않으며 프로세스 인수로 전달되지 않습니다. 먼저 키를 생성해야 하나요? 설정 가이드에서 스크린샷과 함께 OPNsense 쪽을 안내합니다.

2. 어시스턴트 연결

claude mcp add opnsense --transport stdio --env READ_ONLY=true -- npx -y @gabrielion/opnsense-mcp

[mcp_servers.opnsense]
command = "npx"
args = ["-y", "@gabrielion/opnsense-mcp"]

[mcp_servers.opnsense.env]
READ_ONLY = "true"

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "opnsense": {
      "type": "local",
      "command": ["npx", "-y", "@gabrielion/opnsense-mcp"],
      "environment": { "READ_ONLY": "true" }
    }
  }
}

3. 질문하기

내 OPNsense 시스템 상태는 무엇인가요?

내 방화벽에서 어떤 서비스가 실행 중인가요?

먼저 /mcp를 실행하세요: 서버가 connected로 표시되어야 합니다. 추가한다고 해서 자격 증명이 검증되는 것은 아니므로, connected가 실제 신호입니다.

[!TIP] 방화벽이 없거나, 아직 내 방화벽에 적용할 준비가 안 되셨나요? npm run test:product1b는 일회용 OPNsense VM을 부팅하고, 사용자의 자격 증명 없이 자체 최소 권한 계정을 생성하며, 전체 읽기 표면을 대상으로 검증한 후 정리합니다.

Related MCP server: OPNsense MCP Server

현재 작동하는 기능

기본적으로 설치된 서버는 네 가지 읽기 전용 도구를 노출합니다:

• server_status는 MCP 프로세스와 읽기 전용 상태를 확인합니다.

• opn_describe는 에이전트가 사용하기 전에 보이는 리소스를 설명합니다.

• opn_get은 단일 리소스 system.status를 읽습니다.

• opn_list는 컬렉션 리소스 core.services와 firewall.alias를 페이지 단위로 나열합니다. 별칭의 경우 호스트 항목만 나열하며, 보고된 총계도 해당 항목만 셉니다. 다른 별칭 유형은 표시되지 않습니다.

세 가지 MCP 프롬프트도 항상 등록됩니다 — diagnose_network_problem, publish_internal_service, block_domain_for_device. 이들은 읽기 전용 준비 계획만 생성하며 아무것도 실행하지 않습니다.

READ_ONLY=true가 기본값이며, 이 상태에서는 쓰기 도구가 나열되거나 디스패치될 수 없습니다.

opn_create와 opn_delete라는 두 가지 실험적 쓰기 도구가 있으며, firewall.alias의 호스트 항목에만 작동합니다. 세 가지 조건과 지원되는 전송 방식이 이들이 나열될지 여부를 결정합니다:

• READ_ONLY=false;

• ENABLED_FEATURE_FLAGS에 experimental-alias-write 포함;

• ALLOWED_RESOURCES에 firewall.alias가 명시적으로 지정. 허용 목록이 없거나 비어 있으면 모든 읽기를 승인하고 어떤 쓰기도 승인하지 않습니다. 허용 목록은 읽기도 필터링하므로, 계속 사용하려는 모든 범위를 지정하세요. 예: ALLOWED_RESOURCES=server.status,system.status,core.services,firewall.alias;

• 전송 방식은 stdio 또는 Streamable HTTP. 레거시 SSE는 이들을 나열하거나 디스패치하지 않습니다.

네 번째 조건은 나열이 아닌 호출을 규율합니다: 클라이언트가 양식 유도(form elicitation)를 협상해야 합니다. 이 기능이 없는 클라이언트는 도구를 볼 수는 있지만, 모든 시도에서 챌린지나 쓰기 전에 CONFIRMATION_UNAVAILABLE로 거부됩니다.

모든 쓰기는 다음 고정 봉투(envelope)를 이 순서대로 실행합니다: 권한 부여, 변경 사항을 명명하는 인간 확인, 대상에 대한 배타적 잠금, 부작용 없는 사전 점검, 편집된 감사 의도, 검증된 변경 전 백업, 관찰된 상태가 이동하지 않았는지 재확인, 쓰기, 결과 검증, 최종 감사 기록, 잠금 해제. 백업 이후의 모든 실패는 백업을 보존하며 절대 무조건 복원하지 않습니다.

이러한 쓰기가 실험적인 데는 이유가 있습니다. 변경 전 백업은 프로세스별 임시 디렉터리에 기록되며, 서버가 종료되면 삭제되므로 나중에 참조할 수 없습니다. 감사는 가장 최근 1024개 레코드(쓰기당 2개)만 보관하는 인메모리 링이며, 영구 저장 형태도 이를 읽는 도구도 없습니다. 잠금은 프로세스 로컬이므로 같은 방화벽을 가리키는 두 서버는 서로를 배제하지 않습니다.

봉투가 보장하는 것은 좁지만 실제적입니다: 검증된 백업과 감사 의도가 먼저 기록되지 않으면 쓰기가 거부됩니다. 복원이나 롤백은 없습니다 — 변경 적용 후 실패가 발생하면 변경은 적용된 상태로 유지되며 복구는 OPNsense 자체 구성 기록을 통해 수동으로 수행합니다. 이 상태를 영구적으로 만드는 것이 다음 마일스톤입니다.

빠른 로컬 검증

요구 사항: Node.js 22.19 이상(22 메이저 버전 내), npm, macOS 또는 Linux.

if test -x /opt/homebrew/opt/node@22/bin/node; then
  export PATH="/opt/homebrew/opt/node@22/bin:$PATH"
fi
node -e "const [major, minor] = process.versions.node.split('.').map(Number); process.exit(major === 22 && minor >= 19 ? 0 : 1)" &&
npm ci --ignore-scripts &&
npm run test:product1a &&
npm run build

npm run test:product1a는 깨끗한 npm tarball을 생성하고, 격리된 소비자 프로젝트에 설치하며, 별도로 소유한 합성 HTTPS OPNsense 대상에 연결하고, 원시 MCP stdio를 통해 세 가지 OPNsense 도구를 모두 호출하며, 시크릿이 절대 나타나지 않는지 확인하고, EOF에서 종료하며, 모든 픽스처를 제거합니다.

OPNsense 인스턴스 연결

자격 증명을 제공하는 지원 방식은 대화형 명령으로, 올바른 소유권과 모드로 개인 파일을 작성해 줍니다. 클론에서 실행하면 빌드된 엔트리 포인트의 하위 명령입니다:

if test -x /opt/homebrew/opt/node@22/bin/node; then
  export PATH="/opt/homebrew/opt/node@22/bin:$PATH"
fi
node -e "const [major, minor] = process.versions.node.split('.').map(Number); process.exit(major === 22 && minor >= 19 ? 0 : 1)" &&
node dist/main.js configure

레지스트리에서 설치한 경우 동일한 하위 명령은 npx -y @gabrielion/opnsense-mcp configure입니다.

HTTPS 오리진, API 키, API 시크릿, 선택적 CA 파일과 TLS 서버 이름을 묻습니다. 시크릿은 에코되지 않으며 프로세스 인수에 나타나지 않습니다. Windows에서의 실행과 모든 인수를 거부합니다.

항상 플랫폼 경로에 작성하며 OPNSENSE_CONFIG_FILE을 무시합니다. 이는 서버 측 변수입니다:

• macOS: ~/Library/Application Support/opnsense-mcp/config.json;

• Linux: $XDG_CONFIG_HOME/opnsense-mcp/config.json, 없으면 ~/.config/opnsense-mcp/config.json.

서버는 동일한 경로를 발견하므로, 이 변수는 다른 곳에 보관된 파일을 읽을 때만 필요합니다. 소유한 각 디렉터리는 모드 0700으로, 파일은 모드 0600으로 생성됩니다. 심볼릭 링크, 외부 소유자, 안전하지 않은 상위 경로는 거부됩니다.

두 가지 실질적 제한: 기존 구성을 절대 덮어쓰지 않으므로, 키를 교체하려면 먼저 파일을 삭제해야 합니다. 또한 두 스트림 모두 실제 터미널이 필요하므로 파이프나 CI에서 실행할 수 없습니다. 모든 실패는 의도적으로 Error라는 단어 하나만 출력합니다 — 진단은 의도적으로 불투명하여 개인 경로나 자격 증명에 대한 정보가 누출되지 않습니다.

또는 저장소 외부에서 JSON 파일을 직접 만들고 모드 0600으로 보호하세요:

{
  "url": "https://192.0.2.1",
  "apiKey": "your-dedicated-read-only-api-key",
  "apiSecret": "your-api-secret",
  "caFile": "/absolute/path/to/your-ca.pem",
  "tlsServerName": "firewall.example.internal"
}

파일은 현재 사용자가 소유한 일반 파일(심볼릭 링크 아님)이어야 하며, 절대 경로에 있고, 정확히 모드 0600, 정확히 하나의 하드 링크, 최대 16KiB여야 합니다. 0400도 거부됩니다. url은 정확히 하나의 HTTPS 오리진이어야 합니다. 방화벽 인증서가 이미 신뢰할 수 있는 CA에 체인되는 경우 caFile은 선택 사항입니다. URL이 IP 주소를 사용하지만 검증된 인증서가 DNS 이름을 사용하는 경우 tlsServerName은 선택 사항입니다. TLS 검증은 항상 활성화된 상태로 유지됩니다. 전용 최소 권한 OPNsense 키를 사용하세요. 자격 증명을 채팅이나 명령 인수에 붙여넣지 마세요.

전송 방식. stdio가 기본값이며 패키징된 검증에서 종단 간 테스트된 유일한 전송 방식입니다. dist/main.js는 항상 stdio로 시작합니다. Streamable HTTP 전송은 MCP_HTTP_ENABLED 뒤의 별도 엔트리 포인트(npm run start:http)로 존재하며, 루프백에 바인딩되고 Host/Origin 허용 목록과 최소 32자의 bearer MCP_HTTP_TOKEN을 사용합니다. 클라이언트 스모크 테스트로 검증되지 않았으므로 이에 대한 클라이언트 지원 주장은 하지 않습니다. 레거시 SSE 호환 표면은 MCP_LEGACY_SSE_ENABLED 뒤에 존재하며, 이는 추가로 MCP_HTTP_ENABLED=true를 요구합니다 — 단독으로 설정하면 시작 오류입니다 — 그리고 확인 기반 쓰기 도구를 절대 노출하지 않습니다.

프로토콜에 깨끗한 stdio 서버를 직접 실행하려면:

if test -x /opt/homebrew/opt/node@22/bin/node; then
  export PATH="/opt/homebrew/opt/node@22/bin:$PATH"
fi
node -e "const [major, minor] = process.versions.node.split('.').map(Number); process.exit(major === 22 && minor >= 19 ? 0 : 1)" &&
OPNSENSE_CONFIG_FILE="/absolute/path/to/opnsense.json" READ_ONLY=true node dist/main.js

개발이나 테스트를 프로덕션 방화벽에 절대 적용하지 마세요. 실제 작업에는 아래의 일회용 VM 검증을 사용하세요.

일회용 OPNsense 26 검증

macOS 또는 Linux에서 QEMU와 Node.js 22를 설치한 후 실행하세요:

npm run vm:doctor
npm run test:product1b

vm:doctor는 머신을 변경하지 않고 누락된 각 호스트 종속성을 보고합니다. test:product1b는 전체 라이브 테스트를 소유합니다: 고정된 공식 OPNsense 26.7 nano 이미지를 검증하고 캐시하며, 로컬 VM 하나를 시작하고, 운영자 자격 증명 없이 직렬 콘솔을 통해 일회용 최소 권한 API 사용자를 생성하고, 이 npm 패키지를 패킹하여 설치하고, 하나의 MCP 세션을 통해 server_status, opn_describe system.status, opn_get system.status, opn_list core.services를 호출한 다음 VM을 중지하고 오버레이, API 자격 증명, 인증서, 임시 패키지를 제거합니다. 첫 실행은 약 557MB 아카이브를 다운로드하고 사용자 캐시에 3GiB 읽기 전용 기본 이미지를 생성합니다.

역사적 Product 1B 증거는 두 가지 원격 호출에 대한 증거로만 남아 있습니다: GET /api/core/system/status 및 POST /api/core/service/search. 정리된 기계 판독 가능 증거는 방화벽 데이터나 자격 증명을 보관하지 않고 정확한 호스트, QEMU, 펌웨어, 전송 및 정리 검사를 기록합니다.

별칭 쓰기 구현은 변경 전 백업을 위해 GET /api/core/backup/download/this를 대상으로 한 다음 POST /api/firewall/alias/searchItem, addItem 또는 delItem/{uuid}, 그리고 reconfigure 적용을 수행합니다. 이러한 엔드포인트 세부 사항은 결정적 합성 대상 커버리지를 갖습니다. Product 3은 일회용 VM에서 다음만 증명합니다: 쓰기 가능한 표면과 이 정확한 firewall.alias 수명 주기: 부재, 생성, 존재, 삭제, 부재, 이후 VM 정리 및 잔여물 없는 검사. 커밋 바인딩 Product 3 VM 증명은 방화벽 데이터나 자격 증명을 보관하지 않고 테스트된 커밋과 트리, 고정된 펌웨어 이미지, 정책 입력 및 고정된 수명 주기 검사를 기록합니다. Product 3 증명은 프로덕션 사용, 영구 상태, 영구 백업, 영구 감사 추적, 복원 또는 자동 롤백을 증명하지 않습니다.

복원 왕복(restore round-trip)은 또한 동일한 별칭 변경을 API가 아닌 일회용 VM의 콘솔을 통해 직접 되돌린 다음 API를 다시 관찰하여 변경이 사라졌는지 확인합니다. 복원 왕복 Product 3 VM 증명은 테스트된 커밋과 트리, 동일한 고정 펌웨어 이미지와 정책 입력, 별칭 수명 주기 검사, 백업 복원 및 상태 되돌림 검사를 기록하며, 역시 방화벽 데이터나 자격 증명을 보관하지 않고 node scripts/vm/product3-restore.mjs --attestation-out "$PWD/docs/evidence/product3-restore-vm.json"로 생성됩니다.

일회용 계정 권한. 계정은 정확히 이러한 기본 ACL로 생성되며, 그 외에는 아무것도 없습니다. 두 ACL 프로필 모두 이제 정확한 시나리오에서만 실증 데이터를 보유합니다: 읽기 전용 프로필은 Product 1B, 별칭 쓰기 프로필은 Product 3입니다.

• 읽기 전용 계정: page-system-status, page-status-services, user-config-readonly;

• 별칭 쓰기 계정: page-system-status, page-status-services, page-diagnostics-configurationhistory, page-firewall-alias-edit.

user-config-readonly는 별칭 쓰기 계정에서 의도적으로 제외되었습니다: 이 권한이 OPNsense 변경 가능 모델 컨트롤러가 별칭 저장을 거부하게 만드는 것을 관찰했습니다. page-diagnostics-configurationhistory는 변경 전 구성 백업 요청을 위해 부여됩니다. 두 진술 모두 인용된 상위 매핑이 아닌 우리 자신의 부트스트랩 경험에서 나온 것입니다.

OpenCode

프로젝트 수준의 opencode.json을 추가합니다(두 절대 경로를 모두 교체):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "opnsense": {
      "type": "local",
      "command": ["node", "/absolute/path/to/OPNSenseMCP/dist/main.js"],
      "environment": {
        "READ_ONLY": "true",
        "OPNSENSE_CONFIG_FILE": "/absolute/path/to/opnsense.json"
      }
    }
  }
}

그런 다음 opencode mcp list를 실행합니다. opnsense가 연결되어 있어야 합니다. 커밋된 스모크 증거는 설치된 tarball과 합성 HTTPS 대상을 상대로 한 OpenCode 1.18.16 및 opencode/deepseek-v4-flash-free만 다룹니다. 이는 도구/결과 다이제스트를 기록하며, 방화벽 데이터나 자격 증명은 기록하지 않습니다. 기계 판독 가능 증거를 참조하십시오.

다른 MCP 클라이언트도 동일한 stdio 명령을 실행할 수 있지만, 자체 버전이 지정된 스모크 테스트를 통과하기 전까지는 클라이언트별 지원 주장을 하지 않습니다.

이 미리보기가 테스트되는 방법

• 엄격한 TypeScript, 포맷팅, 린트, 라이선스 헤더, 결정적 단위/통합 테스트.

• 합성 대상을 상대로 한 깨끗한 npm pack/install 및 TLS, Basic 인증, 응답 검증, 비밀 정보 삭제, 종료, 정리.

• 두 가지 Product 1B 원격 호출을 위해 일회용 OPNsense 26.1.6 VM을 상대로 한 과거의 깨끗한 npm pack/install. VM 소유권, 고정 이미지 무결성, 격리된 자격 증명, TLS 고정, 역방향 정리를 포함합니다.

• 쓰기 가능한 표면과 정확한 호스트 별칭 수명 주기(부재, 생성, 존재, 삭제, 부재)를 위해 일회용 OPNsense 26.7 VM을 상대로 한 커밋 바인딩 Product 3 실행. 그 후 VM 정리 및 잔여물 없는 검사가 이어집니다.

• 합성 대상 증명 및 두 VM 러너 모두를 위한 밀폐형 패키지 설치: 소비자는 잠금 파생 루프백 전용 npm 레지스트리에서 모든 종속성을 해결하며, 빈 캐시와 연결 불가능한 프록시를 사용하므로 인터넷 액세스가 개입되지 않고 상위 릴리스가 설치된 항목을 변경할 수 없습니다.

• 프로토콜 버전 2025-11-25 및 초안 2026-07-28에 대한 대상 MCP 상호 운용성 검사.

• opencode/deepseek-v4-flash-free를 사용한 실제 OpenCode 1.18.16 라우팅 스모크 테스트 1회.

전체 개발 상태와 기계 간 핸드오프는 docs/project-status.md에 기록되어 있습니다. 계획된 표준 에이전트 평가는 DeepEval 및 OPNsense 평가 설계에 명시되어 있습니다: 이 평가는 Claude Code의 MCP 도구 사용과 최종 응답을 평가하면서, 별도로 일회용 VM 상태의 결정적 MCP 읽기백을 요구합니다. 해당 테스트와 벤치마크 점수는 아직 구현되거나 주장되지 않았습니다.

함께, 이러한 검사는 패키지, 합성 읽기 경로, 명시된 두 가지 과거 Product 1B 원격 호출, 그리고 위에서 명시한 제한된 수명 주기만을 다룹니다. 이는 다음을 증명하지 않습니다:

• 인터넷상의 공개 DNS, ACME 또는 HAProxy 노출;

• 프로덕션 방화벽에 대한 동작;

• 지속적인 백업 또는 지속적인 감사 추적: 둘 다 존재하지만 프로세스 수명 동안만 유효합니다;

• 적용된 변경의 복원 또는 자동 롤백;

• firewall.alias의 호스트 항목 이외의 다른 것에 대한 쓰기;

• 처음 100개 호스트 별칭을 넘어서는 어떤 보장: 변경 전 상태 다이제스트와 읽기백 모두 100개 페이지 하나만 읽으므로, 그 이후에는 생성이 검증되지 않은 결과를 보고할 수 있고 삭제는 항목이 읽은 페이지에 없었다는 것만 증명할 수 있습니다;

• 네이티브 Windows 설치 또는 클라이언트 운영;

• 완전한 에이전트 벤치마크 또는 벤치마크 점수.

원시 API 디스패치, 자유 형식 셸/SSH, 대량 IaC, 대시보드, 광범위한 레거시 동등성은 없습니다.

제품 로드맵 및 예시 요청

변경 안전성 범위(범위 지정 권한 부여, 인간 확인, 검증된 백업, 삭제된 감사, 결과 검증, 실패 시 폐쇄 정리)는 구현되었으며 합성 HTTPS 대상을 상대로 입증되었습니다. 다음 마일스톤은 상태를 지속적으로 만드는 것입니다: 영구 상태 루트, 프로세스 간 잠금, 추가 전용 감사, 로컬 reconcile 명령을 통해 보장이 재시작 후에도 유지되도록 합니다. 그 후에야 별칭 쓰기의 experimental 라벨을 재고할 수 있습니다.

이후의 안내 워크플로는 의도적으로 사용자 수준 목표입니다. 예를 들어:

• "제 노트북이 매일 저녁 인터넷이 끊깁니다. 조사하고 찾은 내용을 설명해 주시겠어요?"

• "다른 기기에 영향을 주지 않고 제 아이의 태블릿에서만 TikTok을 차단해 주세요."

• "이 서비스를 내부적으로 친숙한 DNS 이름, 내부 인증서, 리버스 프록시로 게시해 주세요."

이 세 가지 워크플로는 로드맵 예시이며 Product 1A 주장이 아닙니다. 공개 DNS, Let's Encrypt, HAProxy를 사용한 인터넷 노출 게시는 안전한 쓰기와 개인 VM 적용 범위 이후의 장기 실험실 마일스톤입니다.

배포 상태: npm에 @gabrielion/opnsense-mcp로 게시되었으므로 npx -y @gabrielion/opnsense-mcp는 릴리스된 서버를 실행합니다. git-URL 설치도 prepare 스크립트를 통해 자체 dist/를 빌드합니다. 패키지된 증명은 어느 쪽이든 잠금 파생 루프백 레지스트리가 제공하는 로컬 빌드 tarball을 설치하므로, 이들이 실행하는 것은 레지스트리 사본이 아닌 이 트리입니다. 아직 버전 관리 또는 업그레이드 보장은 제공되지 않습니다.

플랫폼 상태: macOS와 Linux는 현재 검증된 개발 호스트입니다. 네이티브 Windows는 여전히 필수 제품 대상이지만, 이후 windows-2025 게이트를 통과할 때까지 패키지 및 클라이언트 지원을 주장하지 않습니다.

라이선스 및 상표

AGPL-3.0-or-later에 따라 라이선스가 부여됩니다. LICENSE를 참조하십시오. AGPL은 네트워크 사용을 포함한 적용 대상 소스 가용성을 요구하면서 상업적 사용을 허용합니다. OPNsense는 Deciso B.V.의 상표입니다. 이 독립 프로젝트는 Deciso B.V. 또는 OPNsense 프로젝트와 제휴, 후원, 보증 관계가 없습니다.