Connetti in modo sicuro gli agenti AI al server MCP di Webship

# Connetti in modo sicuro gli agenti AI al server MCP di Webship

Una connessione MCP a un server web non è un widget di chat. È un'interfaccia operativa che può ispezionare lo stato della produzione, modificare il routing e le politiche di sicurezza, ricaricare i certificati, attivare versioni statiche, coordinare le modifiche della flotta e installare un aggiornamento firmato Webship.

Trattalo di conseguenza: come un'API amministrativa privilegiata. La configurazione più sicura di Webship mantiene il listener MCP fuori dal piano dati pubblico, lo associa al loopback, lo protegge con TLS 1.3 e un token bearer forte, e vi accede tramite un tunnel SSH autenticato.

Questa guida crea quella configurazione, spiega perché esiste ogni limite e ti fornisce una lista di controllo per gestirla senza trasformare la comodità in esposizione.

Inizia con il confine di fiducia

Il traffico pubblico di Webship e il traffico di MCP utilizzano listener separati. Il piano di controllo di MCP è disabilitato per impostazione predefinita e non condivide mai il normale listener HTTP, HTTP/2, HTTP/3 o WebTransport. Quando abilitato, serve MCP tramite un endpoint dedicato TLS 1.3 HTTP/1.1.

Un'implementazione sicura ha quattro controlli indipendenti:

1. Raggiungibilità della rete: il listener MCP si collega a 127.0.0.1, non a un indirizzo pubblico o LAN privata.
2. Identità del trasporto: il client verifica un certificato emesso da una CA di cui si fida.
3. Autenticazione dell'applicazione: ogni richiesta porta un token bearer forte.
4. Accesso amministrativo: gli operatori raggiungono il listener loopback tramite un account SSH autenticato e un tunnel.

Nessuno di questi controlli sostituisce un altro. TLS senza un percorso di rete privato espone comunque una superficie di autenticazione. Un tunnel senza verifica del certificato rende l'identità del punto finale ambigua. Un token bearer all'interno di un file leggibile da tutto il mondo non è un segreto.

Prepara il certificato e il token

Emettere un certificato MCP dedicato dalla vostra CA interna. Per il tunnel mostrato di seguito, includere localhost e 127.0.0.1 nei nomi alternativi del soggetto del certificato, quindi installare la CA emittente nel trust store del client MCP. Non risolvere un errore di fiducia con un'opzione TLS insicura.

Crea un token unico con almeno 32 byte ASCII stampabili e senza spazi bianchi. Un valore casuale di 32 byte codificato in esadecimale ti dà 64 caratteri sicuri:

umask 077
openssl rand -hex 32

Webship legge attualmente il token MCP direttamente dalla configurazione protetta TOML; token_file non è supportato. Memorizza il risultato in un file di configurazione leggibile solo dall'account di servizio Webship e dal suo gruppo amministrativo. Non inserire il token in un'unità systemd, nella cronologia della shell, in un ticket, in un messaggio di chat o in un prompt inviato a un modello AI.

Su un host Debian tipico:

sudo chown root:webship /etc/webship/production.toml
sudo chmod 0640 /etc/webship/production.toml
sudo chown root:webship /etc/webship/mcp-cert.pem /etc/webship/mcp-key.pem
sudo chmod 0644 /etc/webship/mcp-cert.pem
sudo chmod 0640 /etc/webship/mcp-key.pem

Adatta l'utente e il gruppo del servizio alla tua installazione. La chiave privata e la configurazione devono essere leggibili da Webship, ma non da account non correlati.

Abilita l'ascoltatore isolato

Aggiungi questa sezione alla configurazione attiva Webship:

[security.mcp]
enabled = true
listen = "127.0.0.1:9443"
token = "replace-with-your-generated-64-character-token"
allowed_ips = []
expose_remote = false

[security.mcp.tls]
cert = "/etc/webship/mcp-cert.pem"
key = "/etc/webship/mcp-key.pem"

Una lista vuota allowed_ips non apre l'endpoint. I client loopback rimangono permessi per default. expose_remote = false rende esplicito il confine previsto: se qualcuno in seguito modifica listen in un indirizzo non loopback, Webship rifiuta la configurazione invece di pubblicare silenziosamente il piano di controllo.

Webship rifiuta anche un listener MCP abilitato senza TLS, senza un token, con un token breve o contenente spazi, o con percorsi di certificato vuoti. I token segnaposto pubblici vengono rifiutati prima dell'esposizione remota.

Convalida prima del riavvio

MCP listener, identità TLS e modifiche al token ricostruiscono il piano di controllo, quindi richiedono un riavvio del processo. Verifica prima la configurazione completa:

/usr/local/bin/webship --check-config --config /etc/webship/production.toml
sudo systemctl restart webship
sudo systemctl status webship --no-pager

Conferma che il listener esista solo sul loopback:

ss -ltn | grep '127.0.0.1:9443'

Non aggiungere la porta 9443 alle regole del firewall pubblico dell’host. Il passaggio successivo vi accederà tramite SSH.

Crea il tunnel privato

Dalla workstation dell'amministratore, inoltrare una porta locale all'ascoltatore loopback di Webship:

ssh -N \
  -L 127.0.0.1:19443:127.0.0.1:9443 \
  webship-admin@edge.example.com

Il client MCP ora si connette a https://localhost:19443/mcp. TCP raggiunge il server SSH, SSH trasporta la connessione all'host, e l'host apre la connessione finale a Webship sul loopback. Chiudere la sessione SSH rimuove immediatamente quel percorso.

Usa l'autenticazione SSH basata su chiave, limita quali amministratori possono aprire il tunnel e applica i normali controlli di accesso agli host. Se è necessario un jump host, mantieni il listener MCP sull'interfaccia loopback dell'host Webship ed estendi il percorso SSH piuttosto che ampliare il listener.

Configura il client MCP

I formati di configurazione del client differiscono, ma una voce HTTP MCP tipica appare così:

{
  "mcpServers": {
    "webship-production": {
      "url": "https://localhost:19443/mcp",
      "headers": {
        "Authorization": "Bearer <your-token>"
      }
    }
  }
}

Usa il meccanismo segreto protetto del client quando ne ha uno. Altrimenti, limita la configurazione del client all'account del sistema operativo corrente. Il client HTTP, non il modello, dovrebbe allegare l'intestazione di autorizzazione. Non incollare mai il token live in una conversazione.

Mantieni abilitata la verifica del certificato. Se il client rifiuta il certificato, ripara i nomi alternativi del soggetto del certificato o installa l'CA interna corretta. Non aggiungere un bypass permanente.

Rendi la prima sessione di sola lettura

Dopo che il tunnel e il client sono connessi, iniziare con la scoperta e l'ispezione:

1. Chiedi tools/list; la sua risposta è lo schema argomentativo autorevole per la versione in esecuzione.
2. Chiamare webship.get_config e registrare la versione di configurazione corrente.
3. Ispezionare webship.reverse_proxy.get_status, webship.security.get_status, webship.ddos.get_status e webship.tls.get_status come applicabile.
4. Usa webship.policy.explain o webship.security.simulate prima di cambiare una politica.
5. Conferma che la configurazione restituita offusca i token bearer.

Solo allora testare una mutazione in un ambiente non di produzione. Le mutazioni di configurazione di Webship richiedono l'ID della versione corrente. Una scrittura obsoleta viene rifiutata invece di sovrascrivere una modifica più recente. La politica candidata può essere controllata con la verifica shadow e scenari di traffic-lab prima dell'attivazione.

Webship rifiuta anche i downgrade di sicurezza live selezionati. Una richiesta MCP non può disattivare un WAF attivo, uno strato DDoS, API Shield, la sfida bot, una policy di autenticazione edge o uno strato di intestazioni di risposta. Le modifiche legate al listener, al protocollo, al worker, al runtime e all'autenticazione MCP richiedono un riavvio deliberato.

Quelle guardie riducono gli errori; non rendono innocua ogni azione autorizzata. Il token concede una potente superficie di controllo, comprese le operazioni di aggiornamento e rilascio. Esamina le chiamate agli strumenti proposte esattamente come faresti con un comando shell di un amministratore.

Se il collegamento remoto è inevitabile

Loopback più SSH è il design raccomandato. Se il tuo ambiente richiede un listener su rete privata, rendi esplicita l'eccezione:

[security.mcp]
enabled = true
listen = "10.20.0.15:9443"
expose_remote = true
allowed_ips = ["10.20.10.0/24"]
token = "replace-with-your-generated-64-character-token"

Mantieni il blocco TLS dall'esempio precedente, usa un certificato che corrisponda al nome DNS privato e applica lo stesso intervallo di origine ai firewall dell'host e di rete. Non utilizzare mai 0.0.0.0/0 o ::/0 come whitelist di comodo. Ricorda che una whitelist dell'applicazione vede l'indirizzo di origine che effettivamente raggiunge Webship; verifica il comportamento quando un bilanciatore di carico, un gateway NAT o un service mesh si trova davanti ad esso.

L'esposizione remota aumenta il valore dei log di accesso centralizzati, delle finestre operative brevi e della rotazione rapida. Non è necessaria semplicemente perché il client MCP funziona su un'altra macchina; è esattamente ciò che risolve il tunnel SSH.

Operare il piano di controllo deliberatamente

Usa questa lista di controllo per la produzione:

• Mantieni MCP disabilitato dove nessun agente o operatore ne ha bisogno.
• Collegarsi al loopback e utilizzare un tunnel SSH per impostazione predefinita.
• Utilizzare un'identità TLS dedicata e mantenere abilitata la verifica del certificato.
• Genera un token bearer unico per ciascun ambiente Webship.
• Proteggi il TOML, la configurazione del client, la chiave TLS e le chiavi SSH con i permessi del filesystem.
• Credenziali di sviluppo, test e produzione separate.
• Avvia le sessioni con strumenti di simulazione dello stato e delle politiche prima delle mutazioni.
• Conserva e rivedi gli eventi di audit di sicurezza di Webship.
• Ruotare il token e riavviare Webship dopo una sospetta esposizione.
• Chiudere i tunnel quando la sessione amministrativa termina.

Per la risposta agli incidenti, chiudere i tunnel attivi, limitare l'account SSH, sostituire il token MCP nel TOML protetto, riavviare Webship e rivedere i recenti audit di sicurezza e i record delle versioni di configurazione. Se la chiave privata TLS potrebbe essere stata esposta, emettere un nuovo certificato e una nuova chiave come parte dello stesso riavvio. Testare il vecchio token successivamente e confermare che venga rifiutato.

Un piano di controllo dovrebbe rimanere un piano di controllo

MCP è utile perché un agente può ispezionare lo stato reale e applicare modifiche validate senza indirizzare tali operazioni attraverso il percorso di richiesta pubblico. Questo vantaggio scompare se il listener di controllo diventa un altro endpoint su internet.

Mantieni il confine semplice: un ascoltatore separato, raggiungibilità in loopback, TLS verificato, una credenziale di trasporto protetta, un tunnel autenticato, modifiche controllate per versione e un processo di revisione umana per operazioni potenti. Webship fornisce il protocollo e le protezioni di sicurezza; l'operatore decide chi può raggiungerle.

Questa guida si basa sulla documentazione dell'operatore Webship 1.3.1, sugli esempi di configurazione forniti, sul codice di validazione e trasporto MCP, sulle protezioni della configurazione a runtime e sul catalogo degli strumenti. Esaminate la documentazione corrente Webship e la risposta tools/list del server in esecuzione prima di applicarla a un'altra release.