pfSense MCP 서버

자연어로 pfSense 방화벽을 관리하세요. 327개의 도구. 9단계 안전 장치. 한 번의 명령으로 시작.

You: "Block all traffic from 203.0.113.5 on WAN"
Claude: Creates block rule → applies changes → confirms with rollback instructions

pfSense MCP 서버는 Claude Desktop, Claude Code 및 기타 MCP 호환 AI 클라이언트를 pfSense 방화벽에 연결합니다. 질문하고, 문제를 진단하고, 방화벽을 관리하세요. 이 모든 것이 대화를 통해 이루어집니다.

이 서버가 존재하는 이유

pfSense 방화벽을 관리하려면 웹 UI 탭을 클릭하고, 필드 이름을 기억해야 하며, 실수로 규칙을 잘못 설정하여 접근이 차단되지 않기를 바라야 합니다. 이 MCP 서버를 사용하면 원하는 작업을 평이한 영어로 설명하기만 하면 AI가 REST API 호출을 처리하고, 입력을 검증하며, 파괴적인 작업이 발생하기 전에 경고를 보냅니다.

차별점:

• 모든 파괴적인 작업은 명시적인 확인이 필요하며 정확히 어떤 일이 일어날지 보여줍니다.

• 삭제/재부팅 전 자동 구성 백업 — 한 줄의 롤백 명령 제공.

• 속도 제한(Rate limiting)을 통해 AI 루프가 방화벽에 규칙을 과도하게 생성하는 것을 방지합니다.

• 입력 살균(Input sanitization)을 통해 모든 매개변수에서 명령 주입, 경로 탐색, XSS를 차단합니다.

Related MCP server: Firewalla MCP Server

빠른 시작

전제 조건: Python 3.10+, REST API v2 패키지가 설치된 pfSense

git clone https://github.com/gensecaihq/pfsense-mcp-server.git
cd pfsense-mcp-server
pip install -r requirements.txt
cp .env.example .env
# Edit .env: set PFSENSE_URL, AUTH_METHOD, and credentials

Claude Desktop에 연결 — ~/Library/Application Support/Claude/claude_desktop_config.json에 추가:

{
  "mcpServers": {
    "pfsense": {
      "command": "python3",
      "args": ["-m", "src.main"],
      "cwd": "/path/to/pfsense-mcp-server",
      "env": {
        "PFSENSE_URL": "https://192.168.1.1",
        "AUTH_METHOD": "basic",
        "PFSENSE_USERNAME": "admin",
        "PFSENSE_PASSWORD": "your-password",
        "PFSENSE_VERSION": "CE_2_8_0",
        "VERIFY_SSL": "false"
      }
    }
  }
}

방화벽과 대화 시작. Claude Desktop을 열고 다음과 같이 질문하세요:

• "지난 한 시간 동안 차단된 모든 트래픽을 보여줘"

• "어떤 서비스가 실행 중이야?"

• "포트 443에서 192.168.1.50으로 포트 포워딩을 생성해줘"

• "전체 시스템 상태 점검을 실행해줘"

수행 가능한 작업

모든 주요 pfSense 하위 시스템에 걸친 327개의 도구:

안전 우선

프로덕션 방화벽을 관리하는 AI에는 안전 장치가 필요합니다. 이 서버는 9단계 안전 장치를 갖추고 있습니다:

"Delete firewall rule 5"

  1. CLASSIFY    → HIGH risk (destructive)
  2. ALLOWLIST   → tool is permitted
  3. SANITIZE    → parameters clean (no injection)
  4. RATE LIMIT  → under 10 deletes/minute
  5. DRY RUN?    → user can preview first
  6. CONFIRM     → blocked until confirm=True
  7. BACKUP      → config revision captured
  8. EXECUTE     → API call made
  9. AUDIT LOG   → action recorded with redacted params

Response includes:
  "config_backup": {
    "pre_change_revision_id": 42,
    "rollback_instruction": "restore_config_backup(revision_id=42, confirm=True)"
  }

모든 파괴적인 작업(52개의 삭제/재부팅/중지 도구)은 confirm=True가 필요합니다. 모든 생성 및 업데이트 작업(112개의 도구)은 속도 제한 및 살균 처리가 적용됩니다. 모든 민감한 매개변수(비밀번호, 키, 토큰)는 로그 및 출력에서 마스킹 처리됩니다.

또한 다음을 수행할 수 있습니다:

• dry_run=True를 전달하여 실행하지 않고 파괴적인 작업을 미리보기

• verify_descr="Allow HTTPS"를 전달하여 올바른 규칙을 삭제하는지 확인(ID 변경 방지)

• MCP_READ_ONLY=true를 설정하여 118개의 읽기 전용 도구(검색, 가져오기, 진단)만 노출

• MCP_ALLOWED_TOOLS=search_firewall_rules,get_firewall_log를 설정하여 특정 도구로 제한

지원되는 pfSense 버전

jaredhendrickson13의 pfSense REST API v2 패키지가 필요합니다.

인증

세 가지 방법 지원 (.env에서 구성):

배포 옵션

stdio (기본값) — Claude Desktop 및 Claude Code용:

python3 -m src.main

HTTP — 원격 접근 및 다중 클라이언트 설정용:

python3 -m src.main -t streamable-http --port 3000

Docker — 읽기 전용 파일 시스템이 적용된 강화된 컨테이너:

docker compose up

컨테이너 보안: 비루트 사용자 (mcp:1000), 읽기 전용 파일 시스템, 모든 기능 삭제, noexec tmpfs, no-new-privileges.

구성

테스트

python3 -m pytest tests/ -v          # 308 tests
python3 -m pytest tests/ --cov=src   # with coverage

MCP 사양 준수

MCP 2025-11-25 (최신) 준수:

• 327개 모든 도구에 ToolAnnotations 적용 (readOnlyHint, destructiveHint, idempotentHint)

• serverInfo.version 및 instructions 제공

• 오리진 헤더 검증 (필수 요구 사항)

• 타이밍 안전 비교를 통한 Bearer 토큰 인증

• 사양에 따른 기본 localhost 바인딩

• stdio 및 Streamable HTTP 전송

프로젝트 구조

src/
  main.py              Entry point
  server.py            FastMCP instance + API client
  client.py            pfSense REST API v2 HTTP client
  guardrails.py        9-layer defense-in-depth system
  helpers.py           Validation, parsing, safety guards
  models.py            Data models
  middleware.py        HTTP auth + Origin validation
  tools/               34 tool modules (327 tools)
tests/                 308 tests

기여

다양한 pfSense 환경에서의 실제 테스트가 필요합니다. CONTRIBUTING을 확인하거나 다음을 수행하세요:

1. 포크하고 기능 브랜치를 생성합니다.

2. python3 -m pytest tests/ -v를 실행합니다.

3. PR을 제출합니다.

아이디어: 실제 pfSense에 대한 통합 테스트, 추가 패키지 지원(Snort, Suricata), Ollama 로컬 LLM 브리지, 다중 인스턴스 관리.

라이선스

MIT

감사의 말

• jaredhendrickson13 / pfrest — pfSense REST API v2 패키지

• JeremiahChurch — 모듈식 재작성 (PR #5)

• shawnpetersen — API v2 엔드포인트 검색 (PR #3)

• Netgate — pfSense

• FastMCP — MCP 프레임워크