堡垒分析MCP工具

Requirements

• Python: 3.12 or higher
• FortiAnalyzer: 7.x with JSON-RPC API access enabled
• Authentication: API token (recommended) or username/password
• Network: HTTPS access to FortiAnalyzer management interface

Install dependencies

uv sync ```

Required when running HTTP mode reachable beyond localhost — without it,

Install dev dependencies

uv sync --all-extras

Run integration tests (requires live FAZ)

pytest tests/integration/ -v ```

Note: Integration tests are verified against FortiAnalyzer 7.6.2. Some features (like API rate limiting) require FAZ 7.6.5+.

Installation

Install package

pip install -e . ```

Using Docker

Pre-built images are available on GitHub Container Registry:

docker pull ghcr.io/rstierli/fortianalyzer-mcp:latest

Quick start with Docker Compose:

```yaml

docker-compose.yml

services: fortianalyzer-mcp: image: ghcr.io/rstierli/fortianalyzer-mcp:latest container_name: fortianalyzer-mcp restart: unless-stopped ports: - "8001:8001" env_file: - .env environment: - MCP_SERVER_MODE=http - MCP_SERVER_HOST=0.0.0.0 - MCP_SERVER_PORT=8001 - FORTIANALYZER_HOST=your-faz-hostname - FORTIANALYZER_VERIFY_SSL=true - DEFAULT_ADOM=root - FAZ_TOOL_MODE=full - LOG_LEVEL=INFO

> **Security:** Keep `FORTIANALYZER_VERIFY_SSL=true`. For a self-signed FAZ,
> import the FAZ CA certificate into the container trust store rather than
> disabling verification (disabling it exposes the FAZ API token to MITM).
> In HTTP mode, binding to `0.0.0.0` with no `MCP_AUTH_TOKEN` leaves every tool
> unauthenticated — always set a strong token (below) and, where possible,
> publish the port only on an internal interface (e.g. `127.0.0.1:8001:8001`).

Create a `.env` file for secrets (not tracked in git):

HTTP Authentication (optional, recommended for Docker/HTTP deployments)

Allowed Host headers for HTTP/Docker deployments (optional)

Using the installed command

fortianalyzer-mcp

Docker Mode

```bash

Production Deployment (Reverse Proxy)

For production deployments behind a TLS-terminating reverse proxy:

MCP Client → HTTPS → Reverse Proxy (Traefik/nginx) → HTTP → MCP Container → FortiAnalyzer

Key considerations:

1. MCP_ALLOWED_HOSTS — The MCP SDK validates the Host header to prevent DNS rebinding attacks. By default only localhost and 127.0.0.1 are accepted. Set this to the value clients put in their connection URL (NOT the client's IP):

   # Reverse-proxy hostname (Traefik/nginx):
   MCP_ALLOWED_HOSTS=["mcp.example.com"]
   # Direct Docker exposure on IP+port:
   MCP_ALLOWED_HOSTS=["10.1.5.62:8001"]
   # Port wildcard (any port on the host):
   MCP_ALLOWED_HOSTS=["10.1.5.62:*"]
   

1. MCP_AUTH_TOKEN — Always set a Bearer token for HTTP deployments. If it is unset, the server runs fail-open: every tool (log search, device add/delete, PCAP download) is exposed unauthenticated to anyone who can reach the port.

   MCP_AUTH_TOKEN=$(openssl rand -hex 32)
   

1. Secrets management — Keep API tokens and auth tokens in an env_file (.env), not inline in docker-compose.yml.

Example with Traefik:

services:
  fortianalyzer-mcp:
    image: ghcr.io/rstierli/fortianalyzer-mcp:latest
    container_name: fortianalyzer-mcp
    restart: unless-stopped
    security_opt:
      - no-new-privileges:true
    env_file:
      - .env
    environment:
      - MCP_SERVER_MODE=http
      - MCP_SERVER_HOST=0.0.0.0
      - MCP_SERVER_PORT=8001
      - FORTIANALYZER_HOST=your-faz-hostname
      - FORTIANALYZER_VERIFY_SSL=true
      - MCP_ALLOWED_HOSTS=["mcp.example.com"]
      - DEFAULT_ADOM=root
      - FAZ_TOOL_MODE=full
      - LOG_LEVEL=INFO
    networks:
      - frontend
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.faz-mcp-secure.entrypoints=https"
      - "traefik.http.routers.faz-mcp-secure.rule=Host(`mcp.example.com`)"
      - "traefik.http.routers.faz-mcp-secure.tls=true"
      - "traefik.http.services.faz-mcp.loadbalancer.server.port=8001"
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"

networks:
  frontend:
    external: true

Examples: ["mcp.example.com"], ["10.1.5.62:8001"], or wildcard ["10.1.5.62:*"]

MCP_ALLOWED_HOSTS=["mcp.example.com"]

```

Usage Examples

Create and activate virtual environment

uv venv source .venv/bin/activate # On Windows: .venv\Scripts\activate

Create virtual environment

python -m venv .venv source .venv/bin/activate

.env

FORTIANALYZER_API_TOKEN=your-api-token

Configuration

Environment Variables

Create a .env file from the example:

cp .env.example .env

Edit .env with your FortiAnalyzer settings:

```bash

Authentication Option 1: API Token (Recommended for FAZ 7.2.2+)

FORTIANALYZER_API_TOKEN=your-api-token-here

Authentication Option 2: Username/Password

Request Settings

FORTIANALYZER_TIMEOUT=30 FORTIANALYZER_MAX_RETRIES=3

Default ADOM (optional, defaults to "root")

DEFAULT_ADOM=root

Then update the "command" path in claude_desktop_config.json

```

Fix (alternative): grant Claude Desktop Full Disk Access — System Settings → Privacy & Security → Full Disk Access → add Claude. Broader permission; only use if relocation isn't feasible.

Set up environment

export FORTIANALYZER_HOST=your-faz-host export FORTIANALYZER_API_TOKEN=your-token

Set in .env or environment

MCP_AUTH_TOKEN=your-secret-token ```

When configured, all HTTP requests (except /health) must include the Authorization: Bearer <token> header. If not set, the server runs fail-open: it accepts all requests without authentication (kept for backwards compatibility). In HTTP mode this means every tool — including device add/delete and PCAP download — is reachable by anyone who can connect to the port. Always set MCP_AUTH_TOKEN for any HTTP deployment reachable beyond 127.0.0.1, and prefer binding to an internal interface.

Environment File Permissions

Protect your .env files containing API tokens:

chmod 600 .env .env.*

The MCP SDK rejects non-localhost Host headers by default for DNS rebinding protection.

Generating an API Token

1. Log into FortiAnalyzer web interface
2. Go to System Settings > Admin > Administrators
3. Edit your admin user or create a new one
4. Under JSON API Access, click Regenerate or New API Key
5. Copy the generated token

API Reference

The server communicates with FortiAnalyzer using the JSON-RPC API over HTTPS. All requests are sent to the /jsonrpc endpoint.

Or using Python module

python -m fortianalyzer_mcp ```

Claude Desktop Integration

Add to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "fortianalyzer": {
      "command": "/path/to/fortianalyzer-mcp/.venv/bin/fortianalyzer-mcp",
      "env": {
        "FORTIANALYZER_HOST": "your-faz-hostname",
        "FORTIANALYZER_API_TOKEN": "your-api-token",
        "FORTIANALYZER_VERIFY_SSL": "true",
        "DEFAULT_ADOM": "root",
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

Note: Use the full path to the fortianalyzer-mcp executable in your virtual environment. The DEFAULT_ADOM setting is optional and defaults to "root" if not specified.

Claude Code Integration

Add to ~/.claude/mcp_servers.json:

{
  "mcpServers": {
    "fortianalyzer": {
      "command": "/path/to/fortianalyzer-mcp/.venv/bin/fortianalyzer-mcp",
      "env": {
        "FORTIANALYZER_HOST": "your-faz-hostname",
        "FORTIANALYZER_API_TOKEN": "your-api-token",
        "FORTIANALYZER_VERIFY_SSL": "true",
        "DEFAULT_ADOM": "root",
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

Integration Tests

Integration tests require a real FortiAnalyzer instance and are not run in CI.

```bash

CI Workflow

The project uses GitHub Actions for continuous integration:

• Linting: ruff check on all source files
• Type checking: mypy with strict mode
• Unit tests: pytest with coverage reporting
• Python versions: 3.12+

All CI checks must pass before merging pull requests.

Troubleshooting