Administració CLI

lippycat ofereix un conjunt d’ordres CLI per gestionar i inspeccionar desplegaments distribuïts. Aquestes ordres segueixen un patró coherent de verb i objecte i generen JSON per facilitar-ne l’ús en scripts.

flowchart LR
    subgraph Commands["CLI Admin Commands"]
        direction TB
        Show["lc show"]
        List["lc list"]
        Set["lc set"]
        Rm["lc rm"]
    end

    subgraph Targets["Resources"]
        direction TB
        Proc[Processor Status]
        Hunters[Hunter Info]
        Filters[Filters]
        Topo[Topology]
        Ifaces[Interfaces]
    end

    Show --> Proc
    Show --> Hunters
    Show --> Topo
    Show --> Filters
    List --> Ifaces
    List --> Hunters
    List --> Filters
    Set --> Filters
    Rm --> Filters

Totes les ordres remotes es connecten a un processador mitjançant gRPC i comparteixen un conjunt d’opcions de connexió. Les ordres locals (show config, list interfaces) s’executen sense connexió a un processador.

Els resultats d’exemple següents utilitzen valors il·lustratius. Els noms i les descripcions de les interfícies depenen de l’amfitrió; els camps JSON opcionals depenen del desplegament i de la telemetria disponible.

Opcions de connexió

Totes les ordres remotes admeten aquestes opcions. TLS està activat per defecte: cal passar explícitament --insecure per desactivar-lo.

Aquestes opcions també es poden definir al fitxer de configuració, sota remote:

remote:
  processor: "processor.example.com:55555"
  insecure: false
  tls:
    ca: "/etc/lippycat/certs/ca.crt"
    cert: "/etc/lippycat/certs/client.crt"
    key: "/etc/lippycat/certs/client.key"
    skip_verify: false

Inspecció amb lc show

L’ordre show obté informació d’un processador en execució. Totes les subordres excepte show config requereixen -P.

show status

Mostra l’estat del processador i les estadístiques agregades:

lc show status -P processor:55555 --tls-ca ca.crt

{
  "storage": {
    "filters": {
      "mode": "yaml",
      "state": "ready",
      "last_outcome": "committed",
      "commits": 3
    }
  },
  "processor_id": "central-proc",
  "status": "healthy",
  "total_hunters": 1,
  "healthy_hunters": 1,
  "warning_hunters": 0,
  "error_hunters": 0,
  "total_packets_received": 12500,
  "total_packets_forwarded": 0,
  "total_filters": 3
}

show hunter

Mostra els detalls d’un Hunter concret:

lc show hunter --id edge-01 -P processor:55555 --tls-ca ca.crt

{
  "hunter_id": "edge-01",
  "hostname": "capture-node-1",
  "remote_addr": "10.0.1.10:45678",
  "status": "healthy",
  "connected_duration_sec": 3600,
  "interfaces": ["eth0"],
  "stats": {
    "packets_captured": 500000,
    "packets_matched": 12500,
    "packets_forwarded": 12500,
    "packets_dropped": 0,
    "capture_buffer_regular_drops": 0,
    "capture_buffer_sip_drops": 0,
    "capture_buffer_sip_demotions": 0,
    "batch_channel_drops": 0,
    "capture_buffer_regular_len": 0,
    "capture_buffer_regular_capacity": 1000,
    "capture_buffer_sip_len": 0,
    "capture_buffer_sip_capacity": 100,
    "capture_buffer_output_len": 0,
    "capture_buffer_output_capacity": 100,
    "buffer_bytes": 1048576,
    "active_filters": 3,
    "cpu_percent": 12.5,
    "memory_rss_bytes": 67108864,
    "rtp_ownership_unresolved": 0,
    "rtp_ownership_ambiguous": 0,
    "identity_inheritance_suppressed": 0,
    "tcp_established_idle_retentions": 0,
    "tcp_pre_rearm_discarded_chunks": 0,
    "tcp_rearm_rejected_chunks": 0
  },
  "capabilities": {
    "filter_types": ["sip_user", "ip_address"],
    "max_buffer_size": 67108864,
    "gpu_acceleration": true,
    "af_xdp": false
  }
}

show topology

Mostra tot l’arbre de la topologia distribuïda. És útil per verificar desplegaments jeràrquics:

lc show topology -P processor:55555 --tls-ca ca.crt

{
  "processor_id": "central-proc",
  "address": ":55555",
  "status": "healthy",
  "hierarchy_depth": 0,
  "reachable": true,
  "hunters": [
    {
      "hunter_id": "edge-01",
      "hostname": "capture-node-1",
      "remote_addr": "10.0.1.10:45678",
      "status": "healthy",
      "connected_duration_sec": 3600,
      "interfaces": ["eth0"],
      "stats": {
        "packets_captured": 500000,
        "packets_matched": 12500,
        "packets_forwarded": 12500,
        "packets_dropped": 0,
        "capture_buffer_regular_drops": 0,
        "capture_buffer_sip_drops": 0,
        "capture_buffer_sip_demotions": 0,
        "batch_channel_drops": 0,
        "capture_buffer_regular_len": 0,
        "capture_buffer_regular_capacity": 1000,
        "capture_buffer_sip_len": 0,
        "capture_buffer_sip_capacity": 100,
        "capture_buffer_output_len": 0,
        "capture_buffer_output_capacity": 100,
        "buffer_bytes": 1048576,
        "active_filters": 3,
        "cpu_percent": 12.5,
        "memory_rss_bytes": 67108864,
        "rtp_ownership_unresolved": 0,
        "rtp_ownership_ambiguous": 0,
        "identity_inheritance_suppressed": 0,
        "tcp_established_idle_retentions": 0,
        "tcp_pre_rearm_discarded_chunks": 0,
        "tcp_rearm_rejected_chunks": 0
      },
      "capabilities": {
        "filter_types": ["sip_user", "ip_address"],
        "max_buffer_size": 67108864,
        "gpu_acceleration": true,
        "af_xdp": false
      }
    }
  ],
  "downstream_processors": [
    {
      "processor_id": "region-east",
      "address": "10.0.2.1:55555",
      "status": "healthy",
      "upstream_processor": "central-proc:55555",
      "hierarchy_depth": 1,
      "reachable": true
    }
  ]
}

show filter

Mostra els detalls d’un filtre concret:

lc show filter --id myfilter -P processor:55555 --tls-ca ca.crt

show config

Mostra la configuració local com a JSON. Aquesta és l’única subordre de show que no requereix connexió a un processador:

lc show config

Llistats amb lc list

list interfaces

Descobreix les interfícies de xarxa disponibles per a la captura. És una ordre local: no cal connexió a un processador:

lc list interfaces

NAME     TYPE       STATE  ADDRESSES                NOTES
eth0     Ethernet   up     192.168.1.42/24           default route
wlan0    Wi-Fi      down   —
lo       Loopback   up     127.0.0.1/8, ::1/128
any      Aggregate  —      —                        all network interfaces

7 additional capture devices hidden; use --all to show them.

La vista per defecte inclou interfícies físiques, de bucle local, VPN/túnel i interfícies de xarxa sense classificar, encara que estiguin inactives. any només apareix quan la biblioteca de captura l’ofereix. S’amaguen els ponts reconeguts, determinats enllaços virtuals com ara veth de contenidors i dispositius TAP de màquines virtuals, i fonts de captura especials com D-Bus i NFQUEUE; les interfícies amb una ruta per defecte detectada continuen visibles. Utilitzeu --all per veure tots els dispositius de captura. Les llistes llargues d’adreces es reparteixen en línies de continuació sense ometre cap adreça.

A Linux, les metadades del sistema operatiu proporcionen els tipus d’interfície, l’estat operatiu i indicacions sobre les rutes per defecte IPv4/IPv6 de la taula d’encaminament principal. Altres plataformes utilitzen les metadades disponibles i indiquen com a desconegudes les dades que no poden obtenir. La indicació de la ruta per defecte no avalua l’encaminament basat en polítiques ni selecciona automàticament la interfície adequada per a la vostra captura.

lc list interfaces --all
lc list interfaces --names
lc list interfaces --json --check

--names imprimeix un nom per línia i no es pot combinar amb --json ni --check. El JSON conté una matriu interfaces, un hidden_count i, opcionalment, warnings. Cada interfície inclou name, type, state i default_route; description i addresses s’inclouen quan estan disponibles. Les entrades d’adreça contenen ip i un prefix_len opcional.

El llistat no comprova els permisos ni requereix root. --check obre breument els dispositius de xarxa mostrats sense mode promiscu i els tanca sense llegir paquets. La columna CAPTURE indica available, unavailable o skipped; els errors apareixen a NOTES. Les fonts de captura especials s’ometen. Amb --json, els resultats utilitzen els camps capture_access i, opcionalment, capture_error. Aquests resultats descriuen l’accés en el moment de la comprovació; les captures posteriors poden utilitzar opcions diferents.

Els errors d’accés a dispositius individuals no fan fallar l’ordre. Els errors d’enumeració retornen un estat de sortida diferent de zero i escriuen diagnòstics a stderr (--json utilitza un objecte d’error JSON). Els avisos de descobriment apareixen a stderr en mode de text/noms i dins del resultat en mode JSON.

list hunters

Llista els Hunters connectats a un processador remot:

Llista tots els Hunters connectats:

lc list hunters -P processor:55555 --tls-ca ca.crt

list filters

Llista els filtres configurats en un processador remot:

Llista tots els filtres:

lc list filters -P processor:55555 --tls-ca ca.crt

Llista els filtres d’un Hunter concret:

lc list filters -P processor:55555 --tls-ca ca.crt --hunter hunter-1

Creació de filtres amb lc set

L’ordre set filter crea o actualitza filtres en un processador (semàntica d’upsert). Funciona en dos modes: en línia i amb fitxer.

Mode en línia

Especifiqueu les propietats del filtre directament mitjançant opcions:

Creeu un filtre d’usuari SIP:

lc set filter -P processor:55555 --tls-ca ca.crt \
  --type sip_user --pattern "alicent@example.com"

Creeu un filtre de domini DNS amb comodí:

lc set filter -P processor:55555 --tls-ca ca.crt \
  --type dns_domain --pattern "*.malware-domain.com"

Creeu un filtre d’empremta TLS JA3:

lc set filter -P processor:55555 --tls-ca ca.crt \
  --type tls_ja3 --pattern e7d705a3286e19ea42f587b344ee6865

Creeu un filtre d’interval IP CIDR:

lc set filter -P processor:55555 --tls-ca ca.crt \
  --type ip_address --pattern "192.168.1.0/24"

Creeu un filtre de compte RADIUS exacte amb una revisió explícita:

lc set filter -P processor:55555 --tls-ca ca.crt \
  --type radius_username --pattern 'alice@example.test' --revision 1

Els filtres MAC requereixen exactament el perfil d’interpretació admès:

lc set filter -P processor:55555 --tls-ca ca.crt \
  --type radius_mac --pattern '02-00-00-00-00-01' --revision 1 \
  --radius-mac-profile calling-station-id-uppercase-hyphen-v1

Creeu un filtre amb un ID i una descripció personalitzats:

lc set filter -P processor:55555 --tls-ca ca.crt \
  --id voip-monitor-01 \
  --type sip_user --pattern "*456789" \
  --description "Monitor calls to 456789"

Seleccioneu Hunters concrets:

lc set filter -P processor:55555 --tls-ca ca.crt \
  --type sip_user --pattern "robb@example.com" \
  --hunters edge-01,edge-02

Si s’omet --id, es genera automàticament un UUID.

Mode amb fitxer (per lots)

Importeu diversos filtres d’un fitxer YAML:

lc set filter -P processor:55555 --tls-ca ca.crt -f filters.yaml

El fitxer YAML utilitza el mateix format que el fitxer de filtres del processador. Els criteris RADIUS compostos han d’utilitzar el mode amb fitxer; consulteu l’esquema i exemple de filtre RADIUS.

Tipus de filtre

Per veure la llista completa de tipus de filtre, descripcions, patrons amb comodins i detalls de coincidència, consulteu l’Apèndix E: Referència dels tipus de filtre.

Opcions de set filter

Eliminació de filtres amb lc rm

Filtre individual

lc rm filter --id myfilter -P processor:55555 --tls-ca ca.crt

Eliminació per lots

Elimineu diversos filtres a partir d’un fitxer d’IDs (un per línia):

lc rm filter -f filter-ids.txt -P processor:55555 --tls-ca ca.crt

El format del fitxer és senzill: un ID de filtre per línia; s’ignoren els comentaris amb # i les línies en blanc.

# VoIP filters to remove
voip-monitor-01
voip-monitor-02

# DNS filter
dns-tunnel-detector

Sortida JSON i codis de sortida

Totes les ordres remotes escriuen JSON a stdout (resultats) i stderr (errors). La sortida es formata amb sagnat quan s’escriu en un terminal i de manera compacta quan es passa per una canonada.

Codis de sortida

Format dels errors

{
  "error": "processor address is required (use --processor or set remote.processor in config)",
  "code": "UNAVAILABLE"
}

Exemples de scripts

Script de comprovació de l’estat

#!/bin/bash
status=$(lc show status -P processor:55555 --tls-ca /etc/lippycat/ca.crt \
  2>/dev/null | jq -r '.status')
if [ "$status" = "healthy" ]; then
    echo "OK"
else
    echo "UNHEALTHY: $status"
    exit 1
fi

Supervisió del nombre de Hunters

watch -n 5 'lc show status -P processor:55555 --tls-ca ca.crt | \
  jq "{total: .total_hunters, healthy: .healthy_hunters}"'

Exportació d’una instantània de la topologia

lc show topology -P processor:55555 --tls-ca ca.crt \
  > topology-$(date +%Y%m%d).json

Cicle de vida dels filtres

Creeu un filtre:

lc set filter -P processor:55555 --tls-ca ca.crt \
  --id suspect-01 --type sip_user --pattern "*456789"

Comproveu que existeix:

lc show filter --id suspect-01 -P processor:55555 --tls-ca ca.crt

Llista tots els filtres:

lc list filters -P processor:55555 --tls-ca ca.crt

Elimineu el filtre quan hàgiu acabat:

lc rm filter --id suspect-01 -P processor:55555 --tls-ca ca.crt