Documentazione

Guida

Quick Start

Benvenuto nella documentazione di JERVAS. Segui questi passaggi per integrare i nostri servizi in meno di 15 minuti.

Crea un Account

Registrati su app.jervas.io e seleziona il piano più adatto. Riceverai le credenziali via email entro 5 minuti.

Genera una API Key

Vai in Settings → API Keys → New Key. Assegna un nome descrittivo e seleziona gli scope necessari.

Prima Chiamata API

Testa l'autenticazione con una richiesta GET /v1/ping. Risposta attesa: 200 OK con payload {"status":"ok","version":"2.1"}.

Configura i Webhook

Registra un endpoint HTTPS per ricevere eventi in tempo reale. JERVAS invia un header X-JERVAS-Signature per la verifica HMAC-SHA256.

Auth

Autenticazione

JERVAS supporta due modalità di autenticazione: API Key per integrazioni server-to-server e OAuth 2.0 per applicazioni che agiscono per conto di utenti.

# API Key Authentication
Authorization: Bearer jrv_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
X-JERVAS-Version: 2025-01
Content-Type: application/json

POST https://auth.jervas.io/oauth/token
{
  "grant_type": "client_credentials",
  "client_id": "your_client_id",
  "client_secret": "your_client_secret",
  "scope": "read:assets write:incidents"
}

◈ Scadenza Token

API Key

Le API Key non scadono automaticamente. Possono essere revocate manualmente o configurate con TTL da 1 giorno a 5 anni.

◈ OAuth Token

Access Token

I token OAuth scadono dopo 3600 secondi. Usa il refresh token per ottenerne uno nuovo senza re-autenticazione.

Reference

API Reference

L'API JERVAS è RESTful, usa JSON e segue le convenzioni OpenAPI 3.1. Base URL: https://api.jervas.io/v1

Endpoint	Metodo	Descrizione	Auth
/ping	GET	Health check e versione API	No
/assets	GET	Lista asset monitorati	API Key
/assets/{id}	GET	Dettaglio asset singolo	API Key
/vulnerabilities	GET	Lista CVE rilevate con filtri	API Key
/incidents	GET POST	Gestione incidenti	OAuth
/incidents/{id}/resolve	POST	Chiudi un incidente	OAuth
/sla/report	GET	Report SLA per periodo	API Key
/ai/query	POST	Query AI Workspace	API Key + scope
/webhooks	GET POST	Gestione endpoint webhook	OAuth

GET /v1/vulnerabilities?severity=critical&limit=10&exploitable=true

# Response 200 OK
{
  "data": [{
    "cve_id": "CVE-2024-1234",
    "cvss": 9.8,
    "epss": 0.94,
    "asset_id": "asset_abc123",
    "exploitable": true,
    "patch_available": true
  }],
  "meta": { "total": 42, "page": 1 }
}

Client Libraries

SDK Ufficiali

◈ Python

jervas-python

pip install jervas-sdk

from jervas import Client
client = Client("jrv_live_xxx")
assets = client.assets.list()

◈ TypeScript

@jervas/sdk

npm install @jervas/sdk

import { JervasClient } from '@jervas/sdk'
const client = new JervasClient('jrv_live_xxx')
const vulns = await client.vulnerabilities.list()

Events

Webhooks

JERVAS invia eventi in tempo reale al tuo endpoint HTTPS. Ogni payload è firmato con HMAC-SHA256 usando il tuo webhook_secret.

import hmac, hashlib
sig = request.headers['X-JERVAS-Signature']
expected = hmac.new(
    secret.encode(), request.body, hashlib.sha256
).hexdigest()
assert hmac.compare_digest(sig, expected)

Evento	Trigger	Payload
vulnerability.new	Nuova CVE rilevata	asset_id, cve_id, cvss, epss
incident.created	Incidente aperto	incident_id, severity, title
incident.resolved	Incidente chiuso	incident_id, duration_min, resolver
sla.breach	SLA violato	service, target, actual, period
compliance.gap	Nuovo gap rilevato	framework, control_id, severity

Sicurezza

Security & Hardening

◈ Crittografia

At-Rest & In-Transit

Tutti i dati sono crittografati at-rest con AES-256-GCM e in transito con TLS 1.3. Le chiavi sono gestite via HSM con rotazione automatica ogni 90 giorni.

◈ Penetration Test

Sicurezza Verificata

JERVAS conduce penetration test annuali con red team esterno certificato OSCP/CREST. I risultati sono disponibili in NDA per clienti Enterprise.

◈ Compliance

Certificazioni

In percorso di certificazione: ISO 27001, SOC 2 Type II. Già conformi a GDPR, NIS2 e DORA per i clienti FS.

◈ Bug Bounty

Responsible Disclosure

Segnala vulnerabilità a security@jervas.io con chiave PGP. Risposta entro 24h. Ricompense fino a €5.000 per vulnerabilità critiche.

Changelog

Release Notes

2025-01-15 · v2.1.0

AI Workspace — Supporto multi-modal e grounding score v2

Aggiunto supporto a immagini e PDF nel RAG pipeline. Grounding score ora include citation density e source diversity. Nuovi guardrail configurabili per output PII.

2024-11-20 · v2.0.0

API v2 GA — Breaking changes rispetto a v1

Nuovo schema autenticazione OAuth 2.0. Paginazione cursor-based su tutti gli endpoint list. Deprecazione endpoint /v1/scan (migrazione a /v2/assets/scan entro 2025-06-01).

2024-09-05 · v1.8.0

ZTNA — Device posture check e policy contestuali

Supporto EDR check (CrowdStrike, SentinelOne, Microsoft Defender). Policy dinamiche basate su geolocation e orario. Miglioramento latenza tunnel del 23%.

Documenta zione