NAV
Python PowerShell
Anglais Français

Introduction

Les utilisateurs de Cyberwatch ont accès à une API permettant de récupérer des informations sur les ordinateurs supervisés et sur leurs vulnérabilités.
Cette page documente les différents point d'accès de l'API. Chaque point d'accès est illustré par des exemples dans la colonne de droite en fonction du client sélectionné.

Cyberwatch vous offre un swagger, disponible à cette adresse.
Cette documentation permet de créer automatiquement des requêtes cURL et de les executer via une authentification basique.

Authentification

L'API de Cyberwatch implémente ApiAuth avec du SHA256-HMAC pour s'assurer de l'intégrité de chaque requête. La procédure consiste en plusieurs étapes :

# Les exemples dans cette documentation sont écrits avec les variables d'environnement suivantes pour
une meilleure clarté.
# Remplacer les variables d'environnement avec vos clés d'API, secret et l'URL de votre instance Cyberwatch.
$API_KEY = "8cc6uWwrINV+3DVAPKalixs..." $SECRET_KEY = "A1M/zCmNQc/VOGW7smuzJn+Bs5cwR5e5iKfWbixGkB..." $API_URL = "https://<cyberwatch_adress>" $client = Get-CyberwatchApi -api_url $API_URL -api_key $API_KEY -secret_key $SECRET_KEY
# Les exemples dans cette documentation sont écrits avec les variables d'environnement suivantes pour
une meilleure clarté.
# Remplacer les variables d'environnement avec vos clés d'API, secret et l'URL de votre instance Cyberwatch.
API_KEY="8cc6uWwrINV+3DVAPKalixs..." SECRET_KEY="A1M/zCmNQc/VOGW7smuzJn+Bs5cwR5e5iKfWbixGkB..." API_URL="https://<cyberwatch_adress>"

  1. Une chaîne canonique est d'abord créée en utilisant l'en-tête HTTP contenant le type de contenu, le contenu sha256, l'URI de la requête et un horodatage. La chaîne canonique est de la forme :
    #{méthode http},#{type du contenu},#{contenu sha256},#{URI de la requête},#{horodatage}
  2. La chaîne est ensuite utilisée pour créer la signature, en calculant la signature SHA256-HMAC avec la clé secrète du client, puis en l'encodant en Base64.
  3. Cette signature est ensuite ajoutée comme en-tête Authorization HTTP suivant la forme :
    #{clé d'accès}:#{signature}

Trouver ses clés API

Pour utiliser l'API Cyberwatch, vous devez d'abord obtenir vos clés d'identification. Pour cela, merci d'appliquer la procédure suivante :

  1. Se connecter à l'interface Cyberwatch
  2. Cliquer sur 'Mon Profil'
  3. Cliquer sur 'Voir mes clés d'API'
  4. Cliquer sur la loupe afin d'avoir les détails de vos clés d'API
  5. Vous obtenez alors vos clés d'API avec un identifiant (ID de la clé d'accès API) et un mot de passe (secret de la clé d'accès API), qui seront utilisés pour vous authentifier.

Niveaux d'accès des clés d'identification

Les clés d'identification ont un niveau d'accès parmi les trois suivants :

Pagination

# Voir la section Authentification pour la définition des variables API_KEY, SECRET_KEY et API_URL

# Cet exemple s'appuie sur la ressource server, mais est applicable à toutes les ressources paginées

FILTERS = {
  "per_page": 10,
  "page": 6
}

>>> CBWApi(API_URL, API_KEY, SECRET_KEY).servers(FILTERS)
# Voir la section Authentification pour la définition de la variable $client

# Cet exemple s'appuie sur la ressource server, mais est applicable à toutes les ressources paginées

PS> $Filters = @{
    "per_page" = "10"
    "page" = "6"
}

PS> $client.servers($Filters)

Les ressources paginées utilisent les paramètres suivants.

Paramètres

Paramètres Description
per_page
Optionnel
Limite le nombre d'objets récupérer par page. Par défaut : 30.
page
Optionnel
Spécifie la page à récupérer. Par défaut : 1.

Ping

Tester le fonctionnement de l'API

# Voir la section Authentification pour la définition des variables API_KEY, SECRET_KEY et API_URL

>>> CBWApi(API_URL, API_KEY, SECRET_KEY).ping()
# Voir la section Authentification pour la définition de la variable $client

PS> $client.ping()

Retourne un objet contenant les champs suivants :

{
    "uuid": "1afa2d17-a47c-4d41-9ee7-7890766942bc"
}

Point d'entrée permettant de tester le fonctionnement de l'API.

Requête HTTP

GET /api/v3/ping

Permissions

Une clé d'API avec un niveau d'accès Lecture Seule est nécessaire.

Gestion des actifs

Actifs

Récupération de tous les actifs

# Voir la section Authentification pour la définition des variables API_KEY, SECRET_KEY et API_URL

>>> CBWApi(API_URL, API_KEY, SECRET_KEY).assets()
# Voir la section Authentification pour la définition de la variable $client

PS> $client.assets()

Retourne un objet contenant les champs suivants :

[
  {
    "id": 74,
    "hostname": "2184acb15848",
    "description": "New description",
    "last_communication": "2019-10-30T10:20:13.000+01:00",
    "reboot_required": false,
    "boot_at": "2019-10-09T08:52:46.000+02:00",
    "category": "server",
    "created_at": "2019-10-30T10:18:59.000+01:00",
    "os": {
        "key": "ubuntu_1804_64",
        "name": "Ubuntu 18.04 LTS",
        "arch": "x86_64",
        "eol": "2023-04-26T02:00:00.000+02:00",
        "short_name": "Ubuntu 18.04",
        "type": "Os::Ubuntu"
    },
    "environment": {
        "id": 2,
        "name": "Medium",
        "confidentiality_requirement": "confidentiality_requirement_medium",
        "integrity_requirement": "integrity_requirement_medium",
        "availability_requirement": "availability_requirement_medium"
    },
    "groups": [
        {
            "id": 14,
            "name": "admin",
            "description": null,
            "color": "#12AFCB"
        }, ...
    ]
  }, ...
]

Point d'entrée permettant de récupérer tous les Actifs.

Requête HTTP

GET /api/v3/assets/servers

Permissions

Une clé d'API avec un niveau d'accès Lecture Seule est nécessaire.

Paramètres de requête

Paramètres Description
category
Optionnel
Filtre les actifs par category.
Valeurs possibles :
  • server
  • desktop
  • hypervisor
  • network_device
environment_id
Optionnel
Filtre les actifs par environment_id.
reboot_required
Optionnel
Filtre les actifs par reboot_required.
Valeurs possibles :
  • true
  • false
os
Optionnel
Filtre les actifs par os.
group_id
Optionnel
Filtre les actifs par group_id.
hostname
Optionnel
Filtre les actifs par hostname.
metadata_key
Optionnel
Filtrer les actifs par clef de métadonnée.
metadata_value
Optionnel
Filtrer les actifs par valeur de métadonnée.
service_name
Optionnel
Filtrer les actifs par nom de service.
service_status
Optionnel
Filtrer les actifs par autorisation de démarrage des services.
package_product
Optionnel
Filtre les actifs par nom de package.
package_vendor
Optionnel
Filtre les actifs par fournisseur de package.
package_version
Optionnel
Filtre les actifs par version de package.
port_number
Optionnel
Filtre les actifs par numéro de port.
port_protocol
Optionnel
Filtre les actifs par protocol de port.
address
Optionnel
Filtre les actifs par adresse IP.

Récupération d'un actif

# Voir la section Authentification pour la définition des variables API_KEY, SECRET_KEY et API_URL

>>> CBWApi(API_URL, API_KEY, SECRET_KEY).asset("74")
# Voir la section Authentification pour la définition de la variable $client

PS> $client.asset(74)

Retourne un objet contenant les champs suivants :

{
    "id": 74,
    "hostname": "2184acb15848",
    "description": "New description",
    "last_communication": "2019-10-30T10:20:13.000+01:00",
    "reboot_required": false,
    "boot_at": "2019-10-09T08:52:46.000+02:00",
    "category": "server",
    "created_at": "2019-10-30T10:18:59.000+01:00",
    "connector": {
        "id": 33,
        "type": "SSH with password",
        "path": "/api/v3/assets/remote_accesses/33"
    },
    "os": {
        "key": "ubuntu_1804_64",
        "name": "Ubuntu 18.04 LTS",
        "arch": "x86_64",
        "eol": "2023-04-26T02:00:00.000+02:00",
        "short_name": "Ubuntu 18.04",
        "type": "Os::Ubuntu"
    },
    "environment": {
        "id": 2,
        "name": "Medium",
        "confidentiality_requirement": "confidentiality_requirement_medium",
        "integrity_requirement": "integrity_requirement_medium",
        "availability_requirement": "availability_requirement_medium"
    },
    "groups": [
        {
            "id": 14,
            "name": "admin",
            "description": null,
            "color": "#12AFCB"
        }, ...
    ],
    "packages": [
        {
            "product": "firefox",
            "type": "Packages::Nvd",
            "vendor": null,
            "version": "84.0.2"
        }, ...
    ],
    "metadata": [
        {
            "key": "system-ram",
            "value": "16879468544"
        }, ...
    ],
    "services": [
        {
            "name": "systemd-time-wait-sync",
            "status": "disabled",
            "updated_at": "2021-02-19T10:42:49.498+01:00"
        }, ...
    ],
    "ports": [
        {
            "port": 443,
            "protocol": "TCP",
            "package": {
                "vendor": null,
                "product": "docker-ce",
                "type": "Packages::Deb",
                "version": "5:19.03.12~3-0~ubuntu-bionic"
            }
        }, ...
    ]
}

Point d'entrée permettant de récupérer un actif.

Requête HTTP

GET /api/v3/assets/servers/<ID>

Permissions

Une clé d'API avec un niveau d'accès Lecture Seule est nécessaire.

Paramètres de requête

Paramètres Description
ID
Obligatoire
ID de l'actif à récupérer.

Suppression d'un actif

# Voir la section Authentification pour la définition des variables API_KEY, SECRET_KEY et API_URL

>>> CBWApi(API_URL, API_KEY, SECRET_KEY).delete_asset("74")
# Voir la section Authentification pour la définition de la variable $client

PS> $client.delete_asset(74)

Retourne un objet contenant les champs suivants :

{
    "id": 74,
    "hostname": "2184acb15848",
    "description": "New description",
    "last_communication": "2019-10-30T10:20:13.000+01:00",
    "reboot_required": false,
    "boot_at": "2019-10-09T08:52:46.000+02:00",
    "category": "server",
    "created_at": "2019-10-30T10:18:59.000+01:00",
    "os": {
        "key": "ubuntu_1804_64",
        "name": "Ubuntu 18.04 LTS",
        "arch": "x86_64",
        "eol": "2023-04-26T02:00:00.000+02:00",
        "short_name": "Ubuntu 18.04",
        "type": "Os::Ubuntu"
    },
    "environment": {
        "id": 2,
        "name": "Medium",
        "confidentiality_requirement": "confidentiality_requirement_medium",
        "integrity_requirement": "integrity_requirement_medium",
        "availability_requirement": "availability_requirement_medium"
    },
    "groups": [
        {
            "id": 14,
            "name": "admin",
            "description": null,
            "color": "#12AFCB"
        }, ...
    ]
}

Point d'entrée permettant de supprimer un actif.

Requête HTTP

DELETE /api/v3/assets/servers/<ID>

Permissions

Une clé d'API avec un niveau d'accès Complet est nécessaire.

Paramètres de requête

Paramètres Description
ID
Obligatoire
ID de l'actif à supprimer.

Découvertes

Récupération de toutes les découvertes

# Voir la section Authentification pour la définition des variables API_KEY, SECRET_KEY et API_URL

>>> CBWApi(API_URL, API_KEY, SECRET_KEY).discoveries()
# Voir la section Authentification pour la définition de la variable $client

PS> $client.discoveries()

Retourne un objet contenant les champs suivants :

[
    {
        "id": 1,
        "name": "Demo",
        "node_id": 1,
        "performed_at": "2021-12-17T17:16:34.000+01:00",
        "period": 86400,
        "status": "Executing",
        "target": "127.0.0.0/8",
        "type": "CbwAssets::Discovery::Nmap"
    }, ...
]

Point d'entrée récupérant toutes les découvertes.

Requête HTTP

GET /api/v3/assets/discoveries

Permissions

Une clé d'API avec un niveau d'accès Lecture Seule est nécessaire.

Relancer une découverte

# Voir la section Authentification pour la définition des variables API_KEY, SECRET_KEY et API_URL

>>> CBWApi(API_URL, API_KEY, SECRET_KEY).relaunch_discovery("1")
# Voir la section Authentification pour la définition de la variable $client

PS> $client.relaunch_discovery("1")

Retourne un objet contenant les champs suivants :

{
    "id": 1,
    "name": "Demo",
    "node_id": 1,
    "performed_at": "2021-12-17T17:16:34.000+01:00",
    "period": 86400,
    "status": "Executing",
    "target": "127.0.0.0/8",
    "type": "CbwAssets::Discovery::Nmap"
}

Point d'entrée permettant de relancer une découverte.

Requête HTTP

PUT /api/v3/assets/discoveries/<id>/relaunch

Permissions

Une clé d'API avec un niveau d'accès Complet est nécessaire.

Paramètres de requête

Paramètres Description
id
Obligatoire
ID de la découverte à relancer.

Suppression d'une découverte

# Voir la section Authentification pour la définition des variables API_KEY, SECRET_KEY et API_URL

>>> CBWApi(API_URL, API_KEY, SECRET_KEY).delete_discovery("1")
# Voir la section Authentification pour la définition de la variable $client

PS> $client.delete_discovery("1")

Retourne un objet contenant les champs suivants :

{
    "id": 1,
    "name": "Demo",
    "node_id": 1,
    "performed_at": "2021-12-17T17:16:34.000+01:00",
    "period": 86400,
    "status": "Executing",
    "target": "127.0.0.0/8",
    "type": "CbwAssets::Discovery::Nmap"
}

Point d'entrée permettant la suppression d'une découverte.

Requête HTTP

DELETE /api/v3/assets/discoveries/<id>

Permissions

Une clé d'API avec un niveau d'accès Complet est nécessaire.

Paramètres de requête

Paramètres Description
id
Obligatoire
ID de la découverte à supprimer.

Actifs découvert

Récupération de tous les actifs découvert

# Voir la section Authentification pour la définition des variables API_KEY, SECRET_KEY et API_URL

FILTERS = {"node_id": 1}

>>> CBWApi(API_URL, API_KEY, SECRET_KEY).hosts(FILTERS)
# Voir la section Authentification pour la définition de la variable $client

PS> $Filters = @{
    "node_id" = 1
}

PS> $client.hosts($Filters)

Retourne un objet contenant les champs suivants :

[
    {
        "id": 6,
        "target": "12.34.56.78",
        "hostname": "host_linux",
        "created_at": "2019-09-24T13:39:34.000+02:00",
        "updated_at": "2019-10-30T10:07:28.000+01:00",
        "node_id": 1,
        "server_ids": [72, 123],
        "discovery": {
            "id": 32,
            "name": "Demo",
            "type": "CbwAssets::Discovery::Nmap"
        }
    }, ...
]

Point d'entrée récupérant tous les actifs découvert.

Requête HTTP

GET /api/v3/assets/hosts

Permissions

Une clé d'API avec un niveau d'accès Lecture Seule est nécessaire.

Paramètres JSON

Paramètres Description
node_id
Optionnel
Filtre les actifs découvert par node_id.
discovery_id
Optionnel
Filtre les actifs découvert par discovery_id.
Pagination
Optionnel
Ce point d'entrée peut être paginé.

Récupération d'un actif découvert

# Voir la section Authentification pour la définition des variables API_KEY, SECRET_KEY et API_URL

>>> CBWApi(API_URL, API_KEY, SECRET_KEY).host("6")
# Voir la section Authentification pour la définition de la variable $client

PS> $client.host("6")

Retourne un objet contenant les champs suivants :

{
    "id": 6,
    "target": "12.34.56.78",
    "hostname": "host_linux",
    "created_at": "2019-09-24T13:39:34.000+02:00",
    "updated_at": "2019-10-30T10:07:28.000+01:00",
    "node_id": 1,
    "server_ids": [72, 123],
    "discovery": {
        "id": 30,
        "name": "",
        "type": "CbwAssets::Discovery::Declarative"
    }
}

Point d'entrée récupérant un actif découvert donné.

Requête HTTP

GET /api/v3/assets/hosts/<ID>

Permissions

Une clé d'API avec un niveau d'accès Lecture Seule est nécessaire.

Paramètres de requête

Paramètres Description
ID
Obligatoire
ID de l'actif découvert à récupérer.

Agents

Récupération de tous les agents

# Voir la section Authentification pour la définition des variables API_KEY, SECRET_KEY et API_URL

>>> CBWApi(API_URL, API_KEY, SECRET_KEY).agents()
# Voir la section Authentification pour la définition de la variable $client

PS> $client.agents()

Retourne un objet contenant les champs suivants :

[
    {
        "id": 1,
        "server_id": 679,
        "node_id": 1,
        "version": "3.2",
        "remote_ip": "12.34.56.78",
        "last_communication": "2018-08-09T16:20:02.000+02:00"
    }, ...
]

Point d'entrée récupérant tous les agents.

Requête HTTP

GET /api/v3/assets/agents

Permissions

Une clé d'API avec un niveau d'accès Lecture Seule est nécessaire.

Paramètres de requête

Paramètres Description
server_id
Optionnel
Filtre les agents par node_id.
node_id
Optionnel
Filtre les agents par type.
version
Optionnel
Filtre les agents par type.
remote_ip
Optionnel
Filtre les agents par type.
Pagination
Optionnel
Ce point d'entrée peut être paginé.

Récupération d'un agent

# Voir la section Authentification pour la définition des variables API_KEY, SECRET_KEY et API_URL

>>> CBWApi(API_URL, API_KEY, SECRET_KEY).agent("31")
# Voir la section Authentification pour la définition de la variable $client

PS> $client.agent(31)

Retourne un objet contenant les champs suivants :

{
    "id": 31,
    "server_id": 902,
    "node_id": 1,
    "version": "3.2",
    "remote_ip": "12.34.56.78",
    "last_communication": "2018-08-20T10:25:12.000+02:00"
}

Point d'entrée récupérant un agent.

Requête HTTP

GET /api/v3/assets/agents/<id>

Permissions

Une clé d'API avec un niveau d'accès Lecture Seule est nécessaire.

Paramètres de requête

Paramètres Description
id
Obligatoire
ID de l'agent à récupérer.

Suppression d'un agent

# Voir la section Authentification pour la définition des variables API_KEY, SECRET_KEY et API_URL

>>> CBWApi(API_URL, API_KEY, SECRET_KEY).delete_agent("31")
# Voir la section Authentification pour la définition de la variable $client

PS> $client.delete_agent(31)

Retourne un objet contenant les champs suivants :

{
    "id": 31,
    "server_id": 902,
    "node_id": 1,
    "version": "3.2",
    "remote_ip": "12.34.56.78",
    "last_communication": "2018-08-20T10:25:12.000+02:00"
}

Point d'entrée permettant la suppression d'un agent.

Requête HTTP

DELETE /api/v3/assets/agents/<id>

Permissions

Une clé d'API avec un niveau d'accès Complet est nécessaire.

Paramètres de requête

Paramètres Description
id
Obligatoire
ID de l'agent à supprimer.

Connexions sans-agent

Récupération de toutes les connexions sans-agent

# Voir la section Authentification pour la définition des variables API_KEY, SECRET_KEY et API_URL

>>> CBWApi(API_URL, API_KEY, SECRET_KEY).remote_accesses()
# Voir la section Authentification pour la définition de la variable $client

PS> $client.remote_accesses()

Retourne un objet contenant les champs suivants :

[
    {
        "id": 34,
        "type": "CbwRam::RemoteAccess::Ssh::WithPassword",
        "address": "35.125.0.1",
        "port": 30125,
        "is_valid": true,
        "last_error": null,
        "server_id": 73,
        "node_id": 1
    }, ...
]

Point d'entrée récupérant toutes les connexions sans-agent.

Requête HTTP

GET /api/v3/assets/remote_accesses

Permissions

Une clé d'API avec un niveau d'accès Lecture Seule est nécessaire.

Paramètres de requête

Paramètres Description
type
Optionnel
Filtre les connexions sans-agent par type.
node_id
Optionnel
Filtre les connexions sans-agent par node_id.
Pagination
Optionnel
Ce point d'entrée peut être paginé.

Récupération d'une connexion sans-agent

# Voir la section Authentification pour la définition des variables API_KEY, SECRET_KEY et API_URL

>>> CBWApi(API_URL, API_KEY, SECRET_KEY).remote_access("34")
# Voir la section Authentification pour la définition de la variable $client

PS> $client.remote_access("34")

Retourne un objet contenant les champs suivants :

{
    "id": 34,
    "type": "CbwRam::RemoteAccess::Ssh::WithPassword",
    "address": "35.125.0.1",
    "port": 30125,
    "is_valid": true,
    "last_error": null,
    "server_id": 73,
    "node_id": 1
}

Point d'entrée récupérant une connexion sans-agent.

Requête HTTP

GET /api/v3/assets/remote_accesses/<id>

Permissions

Une clé d'API avec un niveau d'accès Lecture Seule est nécessaire.

Paramètres de requête

Paramètres Description
id
Obligatoire
ID de la connexion sans-agent à récupérer.

Création d'une connexion sans-agent

# Voir la section Authentification pour la définition des variables API_KEY, SECRET_KEY et API_URL

INFO = {
    "address": "12.34.56.78",
    "type": "CbwRam::RemoteAccess::Snmp",
    "port": "30125",
    "priv_password": "passwordlongenough",
    "auth_password": "master",
    "node_id": "1",
    "server_groups": "Production,Application_Lorem,France"
}

>>> CBWApi(API_URL, API_KEY, SECRET_KEY).create_remote_access(INFO)
# Voir la section Authentification pour la définition de la variable $client

PS> $Info = @{
    "address" = "12.34.56.78"
    "type" = "CbwRam::RemoteAccess::Snmp"
    "port" = "30125"
    "priv_password" = "passwordlongenough"
    "auth_password" = "master"
    "node_id" = "1"
    "server_groups" = "Production,Application_Lorem,France"
}

PS> $client.create_remote_access($Info)

Retourne un objet contenant les champs suivants :

{
    "id": 44,
    "type": "CbwRam::RemoteAccess::Snmp",
    "address": "12.34.56.78",
    "port": 30125,
    "is_valid": true,
    "last_error": null,
    "server_id": null,
    "node_id": 1,
    "server_groups": "Production,Application_Lorem,France"
}

Point d'entrée créant une connexion sans-agent selon les paramètres donnés.

Requête HTTP

POST /api/v3/assets/remote_accesses

Permissions

Une clé d'API avec un niveau d'accès Complet est nécessaire.

Paramètres JSON

Paramètres Description
type
Obligatoire
Type de la connexion sans-agent.
Types possibles :
  • CbwRam::RemoteAccess::Snmp
  • CbwRam::RemoteAccess::Ssh::WithKey
  • CbwRam::RemoteAccess::Ssh::WithKey::NetworkDevice
  • CbwRam::RemoteAccess::Ssh::WithPassword
  • CbwRam::RemoteAccess::Ssh::WithPassword::NetworkDevice
  • CbwRam::RemoteAccess::WinRm::WithNegotiate
  • CbwRam::RemoteAccess::WinRm::WithPlaintextOverSsl
  • CbwRam::RemoteAccess::WinRm::WithSsl
address
Obligatoire
Adresse IP de l'ordinateur cible.
port
Obligatoire
Port de l'ordinateur cible.
node_id
Obligatoire
ID du nœud auquel lier la nouvelle connexion sans-agent.
credential_id
Optionnel

Jeu d'identifiants enregistrés à utiliser, par ID.

Cette option fait conflit avec login, password et key qui ne peuvent pas être définis simultanément.

login
Optionnel
login permettant de se connecter à l'ordinateur (ce champ est requis pour les connections sans agent Wallix/HashiCorp vault, et correspond au champ identifiant).
password
Optionnel
password permettant de se connecter à l'ordinateur.
À utiliser avec une connexion de type :
  • CbwRam::RemoteAccess::Ssh::WithPassword
  • CbwRam::RemoteAccess::Ssh::WithPassword::NetworkDevice
  • CbwRam::RemoteAccess::WinRm::WithNegotiate
  • CbwRam::RemoteAccess::WinRm::WithPlaintextOverSsl
  • CbwRam::RemoteAccess::WinRm::WithSsl
key
Optionnel
Contenu de la clé SSH permettant la connexion à l'ordinateur.
À utiliser avec une connexion de type :
  • CbwRam::RemoteAccess::Ssh::WithKey
  • CbwRam::RemoteAccess::Ssh::WithKey::NetworkDevice
priv_password
Optionnel
Mot de passe de chiffrement permettant de se connecter à l'ordinateur.
À utiliser avec une connexion de type :
  • CbwRam::RemoteAccess::Snmp
auth_password
Optionnel
Mot de passe d'authentification permettant de se connecter à l'ordinateur.
À utiliser avec une connexion de type :
  • CbwRam::RemoteAccess::Snmp
login_path
Optionnel
Chemin vers la variable Conjur contenant le nom d’utilisateur. N’est pertinent que si credential_id désigne des identifiants Conjur.
password_path
Optionnel
Chemin vers la variable Conjur contenant le mot de passe. N’est pertinent que si credential_id désigne des identifiants Conjur.
key_path
Optionnel
Chemin vers la variable Conjur contenant la clé. N’est pertinent que si credential_id désigne des identifiants Conjur.
server_groups
Optionnel
Liste des noms de groupes à associer à l'ordinateur qui sera crée (séparés par des virgules). Les groupes seront visibles sur l'interface après la réussite de la connexion à l'ordinateur.

Modification d'une connexion sans-agent

# Voir la section Authentification pour la définition des variables API_KEY, SECRET_KEY et API_URL

INFO = {"auth_password": "short"}
ID = "44"

>>> CBWApi(API_URL, API_KEY, SECRET_KEY).update_remote_access(ID, INFO)
# Voir la section Authentification pour la définition de la variable $client

PS> $Info = @{"auth_password" = "short"}
PS> $Id = 44

PS> $client.update_remote_access($Id, $Info)

Retourne un objet contenant les champs suivants :

{
    "id": 44,
    "type": "CbwRam::RemoteAccess::Snmp",
    "address": "12.34.56.78",
    "port": 30125,
    "is_valid": false,
    "last_error": "priv password must have between 8 to 32 characters",
    "server_id": null,
    "node_id": 1
}

Point d'entrée permettant de modifier une connexion sans-agent existante.

Requête HTTP

PUT /api/v3/assets/remote_accesses/<id>

Permissions

Une clé d'API avec un niveau d'accès Complet est nécessaire.

Paramètres de requête

Paramètres Description
id
Obligatoire
ID de la connexion sans-agent à modifier.

Paramètres JSON

Paramètres Description
node_id
Optionnel
Nouvel ID du nœud auquel lier le nouvel ordinateur.
address
Optionnel
Nouvelle adresse IP de l'ordinateur cible.
port
Optionnel
Nouveau port de l'ordinateur cible.
credential_id
Optionnel

Jeu d'identifiants enregistrés à utiliser, par ID.

Cette option fait conflit avec login, password et key qui ne peuvent pas être définis simultanément.

Pour remplacer des identifiants explicites par des identifiants enregistrés, vous devez effacer expressément les identifiants déjà configurés. Par exemple en les définissant à nul ou vide dans la requête qui définira credential_id.

login
Optionnel
Nouveau login permettant de se connecter à l'ordinateur.
password
Optionnel
Nouveau password permettant de se connecter à l'ordinateur.
À utiliser avec une connexion de type :
  • CbwRam::RemoteAccess::Ssh::WithPassword
  • CbwRam::RemoteAccess::Ssh::WithPassword::NetworkDevice
  • CbwRam::RemoteAccess::WinRm::WithNegotiate
  • CbwRam::RemoteAccess::WinRm::WithPlaintextOverSsl
  • CbwRam::RemoteAccess::WinRm::WithSsl
key
Optionnel
Nouveau contenu de la clé SSH permettant la connexion à l'ordinateur.
À utiliser avec une connexion de type :
  • CbwRam::RemoteAccess::Ssh::WithKey
  • CbwRam::RemoteAccess::Ssh::WithKey::NetworkDevice
priv_password
Optionnel
Nouveau mot de passe de chiffrement permettant de se connecter à l'ordinateur.
À utiliser avec une connexion de type :
  • CbwRam::RemoteAccess::Snmp
auth_password
Optionnel
Nouveau mot de passe d'authentification permettant de se connecter à l'ordinateur.
À utiliser avec une connexion de type :
  • CbwRam::RemoteAccess::Snmp
login_path
Optionnel
Chemin vers la variable Conjur contenant le nom d’utilisateur. N’est pertinent que si credential_id désigne des identifiants Conjur.
password_path
Optionnel
Chemin vers la variable Conjur contenant le mot de passe. N’est pertinent que si credential_id désigne des identifiants Conjur.
key_path
Optionnel
Chemin vers la variable Conjur contenant la clé. N’est pertinent que si credential_id désigne des identifiants Conjur.

Vérification du déploiement d'une connexion sans-agent

# Voir la section Authentification pour la définition des variables API_KEY, SECRET_KEY et API_URL

>>> CBWApi(API_URL, API_KEY, SECRET_KEY).test_deploy_remote_access("34")
# Voir la section Authentification pour la définition de la variable $client

PS> $client.test_deploy_remote_access("34")

Retourne un objet contenant les champs suivants :

{
    "id": 44,
    "type": "CbwRam::RemoteAccess::Snmp",
    "address": "12.34.56.78",
    "port": 30125,
    "is_valid": null,
    "last_error": "priv password must have between 8 to 32 characters",
    "server_id": null,
    "node_id": 1
}

Point d'entrée permettant de lancer la vérification du déploiement d'une connexion sans-agent.

Requête HTTP

PUT /api/v3/assets/remote_accesses/<id>/test_deploy

Permissions

Une clé d'API avec un niveau d'accès Complet est nécessaire.

Paramètres de requête

Paramètres Description
id
Obligatoire
ID de la connexion sans-agent à vérifier.

Suppression d'une connexion sans agent

# Voir la section Authentification pour la définition des variables API_KEY, SECRET_KEY et API_URL

>>> CBWApi(API_URL, API_KEY, SECRET_KEY).delete_remote_access("44")
# Voir la section Authentification pour la définition de la variable $client

PS> $client.delete_remote_access("44")

Retourne un objet contenant les champs suivants :

{
    "id": 44,
    "type": "CbwRam::RemoteAccess::Snmp",
    "address": "12.34.56.78",
    "port": 30125,
    "is_valid": false,
    "last_error": "priv password must have between 8 to 32 characters",
    "server_id": null,
    "node_id": 1
}

Point d'entrée permettant la suppression d'une connexion sans-agent.

Requête HTTP

DELETE /api/v3/assets/remote_accesses/<id>

Permissions

Une clé d'API avec un niveau d'accès Complet est nécessaire.

Paramètres de requête

Paramètres Description
id
Obligatoire
ID de la connexion sans-agent à supprimer.

Images Docker

Lister toutes les images Docker

# Voir la section Authentification pour la définition des variables API_KEY, SECRET_KEY et API_URL

>>> CBWApi(API_URL, API_KEY, SECRET_KEY).docker_images()
# Voir la section Authentification pour la définition de la variable $client

PS> $client.docker_images()

Retourne un objet contenant les champs suivants :

[
    {
        "docker_engine_id": 93,
        "docker_registry_id": 104,
        "id": 16,
        "image_name": "test/alpine",
        "image_tag": "latest",
        "node_id": 1,
        "server_id": 148
    },
    
]

Requête HTTP

GET /api/v3/assets/docker_images

Permissions

Une clé d'API avec un niveau d'accès Lecture Seule est nécessaire.

Paramètres de requête

Paramètres Description
image_name
Optionnel
Filtrer par nom d’image.
image_tag
Optionnel
Filtrer par tag.
docker_registry_id
Optionnel
Filtrer par registre Docker.
docker_engine_id
Optionnel
Filtrer par moteur d’exécution Docker.
node_id
Optionnel
Filtrer par source.
Pagination
Optionnel
Ce point d'entrée peut être paginé.

Récupérer une image Docker

# Voir la section Authentification pour la définition des variables API_KEY, SECRET_KEY et API_URL

>>> CBWApi(API_URL, API_KEY, SECRET_KEY).docker_image("37")
# Voir la section Authentification pour la définition de la variable $client

PS> $client.docker_image(37)

Retourne un objet contenant les champs suivants :

{
    "docker_engine_id": 93,
    "docker_registry_id": 106,
    "id": 37,
    "image_name": "library/alpine",
    "image_tag": "latest",
    "node_id": 1,
    "server_id": 169
}

Requête HTTP

GET /api/v3/assets/docker_images/<id>

Permissions

Une clé d'API avec un niveau d'accès Lecture Seule est nécessaire.

Paramètres de requête

Paramètres Description
id
Obligatoire
ID de l’image Docker à récupérer.

Ajouter une image Docker

# Voir la section Authentification pour la définition des variables API_KEY, SECRET_KEY et API_URL

INFO = {
    "image_name": "library/debian",
    "image_tag": "latest",
    "docker_registry_id": "106",
    "docker_engine_id": "93",
    "node_id": "1"
}

>>> CBWApi(API_URL, API_KEY, SECRET_KEY).create_docker_images(INFO)
# Voir la section Authentification pour la définition de la variable $client

PS> $Info = @{
    "image_name" = "library/debian"
    "image_tag" = "latest"
    "docker_registry_id" = 106
    "docker_engine_id" = 93
    "node_id" = "1"
}

PS> $client.create_docker_images($Info)

Retourne un objet contenant les champs suivants :

{
    "docker_engine_id": 93,
    "docker_registry_id": 106,
    "id": 40,
    "image_name": "library/debian",
    "image_tag": "latest",
    "node_id": 1,
    "server_id": null
}

Requête HTTP

POST /api/v3/docker_images

Permissions

Une clé d'API avec un niveau d'accès Complet est nécessaire.

Paramètres JSON

Paramètres Description
image_name
Obligatoire
Nom de l’image Docker sur le registre.
image_tag
Obligatoire
Tag de l’image Docker à analyser.
docker_registry_id
Obligatoire
ID d’identifiants enregistrés du registre Docker duquel tirer l’image.
docker_engine_id
Obligatoire
ID d’identifiants enregistrés du moteur d’exécution sur lequel lancer les analyses.
node_id
Obligatoire
ID de la source Cyberwatch qui se connectera au moteur d’exécution Docker.

Modifier une image Docker

# Voir la section Authentification pour la définition des variables API_KEY, SECRET_KEY et API_URL

INFO = {
    "image_tag": "buster"
}

ID = "40"

>>> CBWApi(API_URL, API_KEY, SECRET_KEY).update_docker_images(ID, INFO)
# Voir la section Authentification pour la définition de la variable $client

PS> $Info = @{
    "image_tag" = "buster"
}

PS> $Id = 40

PS> $client.update_docker_images($Id, $Info)

Retourne un objet contenant les champs suivants :

{
    "docker_engine_id": 93,
    "docker_registry_id": 106,
    "id": 40,
    "image_name": "library/debian",
    "image_tag": "buster",
    "node_id": 1,
    "server_id": 174
}

Requête HTTP

PATCH /api/v3/assets/docker_images/<id>

Permissions

Une clé d'API avec un niveau d'accès Complet est nécessaire.

Paramètres de requête

Paramètres Description
id
Obligatoire
ID de l’image Docker à modifier

Paramètres JSON

Paramètres Description
image_name
Optionnel
Nom de l’image Docker sur le registre.
image_tag
Optionnel
Tag de l’image Docker à analyser.
docker_registry_id
Optionnel
ID d’identifiants enregistrés du registre Docker duquel tirer l’image.
docker_engine_id
Optionnel
ID d’identifiants enregistrés du moteur d’exécution sur lequel lancer les analyses.
node_id
Optionnel
ID de la source Cyberwatch qui se connectera au moteur d’exécution Docker.

Enlever une image Docker

# Voir la section Authentification pour la définition des variables API_KEY, SECRET_KEY et API_URL

>>> CBWApi(API_URL, API_KEY, SECRET_KEY).delete_docker_image("40")
# Voir la section Authentification pour la définition de la variable $client

PS> $client.delete_docker_image(40)

Retourne un objet contenant les champs suivants :

{
    "docker_engine_id": 93,
    "docker_registry_id": 106,
    "id": 40,
    "image_name": "library/debian",
    "image_tag": "buster",
    "node_id": 1,
    "server_id": 174
}

Requête HTTP

DELETE /api/v3/assets/docker_images/<id>

Paramètres de requête

Paramètres Description
id
Obligatoire
ID de l’image Docker à enlever

Cibles réseau et sites web

Lister toutes les cibles réseau et les sites web

# Voir la section Authentification pour la définition des variables API_KEY, SECRET_KEY et API_URL

>>> CBWApi(API_URL, API_KEY, SECRET_KEY).applicative_scans()

Retourne un objet contenant les champs suivants :

[
    {
        "id": 16,
        "target": "https://www.cyberwatch.fr/",
        "node_id": 1,
        "server_id": 148
    },
    
]

Requête HTTP

GET /api/v3/assets/applicative_scans

Permissions

Une clé d'API avec un niveau d'accès Lecture Seule est nécessaire.

Paramètres de requête

Paramètres Description
target
Optionnel
Filtre les cibles réseau par Adresse.
node_id
Optionnel
Filtre les cibles réseau par relais.
Pagination
Optionnel
Ce point d'entrée peut être paginé.

Récupérer une cible réseau ou un site web

# Voir la section Authentification pour la définition des variables API_KEY, SECRET_KEY et API_URL

APPLICATIVE_SCAN_ID = '37'

>>> CBWApi(API_URL, API_KEY, SECRET_KEY).applicative_scan(APPLICATIVE_SCAN_ID)

Retourne un objet contenant les champs suivants :

{
    "id": 37,
    "target": "https://www.cyberwatch.fr/",
    "node_id": 1,
    "server_id": 148
}

Requête HTTP

GET /api/v3/assets/applicative_scans/<id>

Permissions

Une clé d'API avec un niveau d'accès Lecture Seule est nécessaire.

Paramètres de requête

Paramètres Description
id
Obligatoire
ID de la cible réseau ou du site web à récupérer.

Ajouter une cible réseau ou un site web

# Voir la section Authentification pour la définition des variables API_KEY, SECRET_KEY et API_URL

INFO = {
    "target": "https://www.cyberwatch.fr/",
    "node_id": "1"
    }

>>> CBWApi(API_URL, API_KEY, SECRET_KEY).create_applicative_scan(APPLICATIVE_SCAN_ID)

Retourne un objet contenant les champs suivants :

{
    "id": 16,
    "target": "https://www.cyberwatch.fr/",
    "node_id": 1,
    "server_id": 148
}

Requête HTTP

POST /api/v3/applicative_scans

Permissions

Une clé d'API avec un niveau d'accès Complet est nécessaire.

Paramètres JSON

Paramètres Description
target
Obligatoire
Adresse de la cible réseau ou du site web.
node_id
Obligatoire
Relais qui effectuera les scans sur la cible réseau ou le site web.

Modifier une cible réseau ou un site web

# Voir la section Authentification pour la définition des variables API_KEY, SECRET_KEY et API_URL

APPLICATIVE_SCAN_ID = '16'

INFO = {
    "target": "10.10.10.1"
    }

>>> CBWApi(API_URL, API_KEY, SECRET_KEY).update_applicative_scan(APPLICATIVE_SCAN_ID)

Retourne un objet contenant les champs suivants :

{
    "id": 16,
    "target": "10.10.10.1",
    "node_id": 1,
    "server_id": 148
}

Requête HTTP

PATCH /api/v3/assets/applicative_scans/<id>

Permissions

Une clé d'API avec un niveau d'accès Complet est nécessaire.

Paramètres de requête

Paramètres Description
id
Obligatoire
ID de la cible réseau ou du site web à modifier

Paramètres JSON

Paramètres Description
target
Optionnel
Adresse de la cible réseau ou du site web.
node_id
Optionnel
Relais qui effectuera les scans sur la cible réseau ou le site web.

Suppression d'une cible réseau ou d'un site web

# Voir la section Authentification pour la définition des variables API_KEY, SECRET_KEY et API_URL

APPLICATIVE_SCAN_ID = '16'

>>> CBWApi(API_URL, API_KEY, SECRET_KEY).delete_applicative_scan(APPLICATIVE_SCAN_ID)

Retourne un objet contenant les champs suivants :

{
    "id": 16,
    "target": "https://www.cyberwatch.fr/",
    "node_id": 1,
    "server_id": 148
}

Requête HTTP

DELETE /api/v3/assets/applicative_scans/<id>

Paramètres de requête

Paramètres Description
id
Obligatoire
ID de la cible réseau ou du site web à enlever

Systèmes d’exploitation

Récupération de tous les systèmes d’exploitation

# Voir la section Authentification pour la définition des variables API_KEY, SECRET_KEY et API_URL

>>> CBWApi(API_URL, API_KEY, SECRET_KEY).operating_systems()
# Voir la section Authentification pour la définition de la variable $client

PS> $client.os()

Retourne un objet contenant les champs suivants :

[
    {
        "arch": "powerpc",
        "eol": "2017-04-30T02:00:00.000+02:00",
        "key": "aix_6_1",
        "name": "Aix 6.1",
        "short_name": "Aix 6.1",
        "type": "Os::Aix"
    }, ...
]

Point d'entrée permettant de récupérer tous les systèmes d’exploitation.

Requête HTTP

GET /api/v3/os

Permissions

Une clé d'API avec un niveau d'accès Lecture Seule est nécessaire.

Paramètres de requête

Paramètres Description
Pagination
Optionnel
Ce point d'entrée peut être paginé.

Gestion des vulnérabilités

Actifs (vulnérabilité)

Récupération de tous les actifs

# Voir la section Authentification pour la définition des variables API_KEY, SECRET_KEY et API_URL

FILTERS = {
    "os": "ubuntu_1910_64",
    "environment_id": "2",
    "category": "server",
    "reboot_required": "false"
}

>>> CBWApi(API_URL, API_KEY, SECRET_KEY).servers(FILTERS)
# Voir la section Authentification pour la définition de la variable $client

PS> $Filters = @{
    "os" = "ubuntu_1910_64"
    "environment_id" = "2"
    "category" = "server"
    "reboot_required" = "false"
}

PS> $client.servers($Filters)

Retourne un objet contenant les champs suivants :

[
    {
        "id": 74,
        "hostname": "2184acb15848",
        "addresses": ["127.0.0.1", "10.10.0.123", ],
        "description": "Old description",
        "last_communication": "2019-10-30T10:20:13.000+01:00",
        "reboot_required": false,
        "updates_count": 1,
        "boot_at": "2019-10-09T08:52:46.000+02:00",
        "category": "server",
        "created_at": "2019-10-30T10:18:59.000+01:00",
        "analyzed_at": "2020-08-19T10:31:51.000+02:00",
        "cve_announcements_count": 4,
        "prioritized_cve_announcements_count": 1,
        "status": "server_update_comm_fail",
        "os": {
            "key": "ubuntu_1910_64",
            "name": "Ubuntu 19.10",
            "arch": "x86_64",
            "eol": "2020-07-31T00:00:00.000+02:00",
            "short_name": "Ubuntu 19.10",
            "type": "Os::Ubuntu"
        },
        "environment": {
            "id": 2,
            "name": "Medium",
            "confidentiality_requirement": "confidentiality_requirement_medium",
            "integrity_requirement": "integrity_requirement_medium",
            "availability_requirement": "availability_requirement_medium"
        },
        "groups": [
            {
                "id": 12,
                "name": "aloalp",
                "description": null,
                "color": "#12AFCB"
            },
            {
                "id": 14,
                "name": "admin",
                "description": null,
                "color": "#12AFCB"
            }
        ],
        "compliance_repositories": [
            {
                "id": 1,
                "name": "CIS_Benchmark",
                "description": null,
                "color": "#336699"
            }
        ]
    }, ...
]

Point d'entrée permettant de récupérer tous les Actifs.

Requête HTTP

GET /api/v3/vulnerabilities/servers

Permissions

Une clé d'API avec un niveau d'accès Lecture Seule est nécessaire.

Paramètres de requête

Paramètres Description
category
Optionnel
Filtre les actifs par category.
Valeurs possibles :
  • server
  • desktop
  • hypervisor
  • network_device
environment_id
Optionnel
Filtre les actifs par environment_id.
reboot_required
Optionnel
Filtre les actifs par reboot_required.
Valeurs possibles :
  • true
  • false
os
Optionnel
Filtre les actifs par os.
group_id
Optionnel
Filtre les actifs par group_id.
hostname
Optionnel
Filtre les actifs par hostname.
address
Optionnel
Filtre les actifs par adresse IP.
communication_failed
Optionnel
Filtre les actifs qui ont échoué ou réussi à communiquer.
Valeurs possibles :
  • true
  • false

Récupération d'un actif

# Voir la section Authentification pour la définition des variables API_KEY, SECRET_KEY et API_URL

>>> CBWApi(API_URL, API_KEY, SECRET_KEY).server("102")
# Voir la section Authentification pour la définition de la variable $client

PS> $client.server("102")

Retourne un objet contenant les champs suivants :

{
    "id": 102,
    "hostname": "MSEDGEWIN10",
    "addresses": ["127.0.0.1", "10.10.0.123", ],
    "description": null,
    "last_communication": "2019-11-29T12:55:42.000+01:00",
    "reboot_required": false,
    "updates_count": 4,
    "boot_at": "2019-11-29T12:08:35.000+01:00",
    "category": "desktop",
    "created_at": "2019-11-29T12:10:27.000+01:00",
    "analyzed_at": "2020-08-19T10:31:51.000+02:00",
    "cve_announcements_count": 473,
    "prioritized_cve_announcements_count": 124,
    "status": "server_vulnerable",
    "cve_announcements": [
        {
            "cve_code": "CVE-2019-0732",
            "ignored": false,
            "comment": "comment",
            "active": false,
            "prioritized": false,
            "detected_at": "2019-11-29T12:10:27.000+01:00",
            "fixed_at": null,
            "score": 7.8
        }, ...
    ],
    "updates": [
        {
            "id": 2544,
            "ignored": false,
            "patchable": true,
            "cve_announcements": [
                "CVE-2019-0732", ...
            ],
            "target": {
                "vendor": null,
                "product": "KB4523205",
                "type": "Packages::Kb",
                "version": "61118c04-b0ba-49af-82b7-05cb038923fb"
            },
            "current": null
        }, ...
    ],
    "security_issues": [
        {
            "id": 51,
            "sid": "Obsolete-Os",
            "level": "level_critical",
            "title": "Obsolete operating system",
            "description": "Description",
            "editable": false,
            "detected_at": "2021-09-01T11:03:30.809+02:00",
            "status": "active",
            "comment": null
        }, ...
    ],
    "os": {
        "key": "windows_10_1809_64",
        "name": "Windows 10 1809",
        "arch": "AMD64",
        "eol": "2021-05-11T00:00:00.000+02:00",
        "short_name": "Win 10 1809",
        "type": "Os::Windows"
    },
    "environment": {
        "id": 2,
        "name": "Medium",
        "confidentiality_requirement": "confidentiality_requirement_medium",
        "integrity_requirement": "integrity_requirement_medium",
        "availability_requirement": "availability_requirement_medium"
    },
    "groups": [],
    "compliance_repositories": []
}

Point d'entrée permettant de récupérer un actif.

Requête HTTP

GET /api/v3/vulnerabilities/servers/<ID>

Permissions

Une clé d'API avec un niveau d'accès Lecture Seule est nécessaire.

Paramètres de requête

Paramètres Description
ID
Obligatoire
ID de l'actif à récupérer.

Exporter un actif

Retourne un objet contenant les champs suivants :

HOSTNAME:MSEDGEWIN10
IP:127.0.0.0
# …

Exporte les données d’un actif dans un format compatible air gap.

Requête HTTP

GET /api/v3/vulnerabilities/servers/<ID>/info

Permissions

Une clé d'API avec un niveau d'accès Lecture Seule est nécessaire.

Paramètres de requête

Paramètres Description
ID
Obligatoire
ID de l'actif à exporter.

Modification d'un actif existant

# Voir la section Authentification pour la définition des variables API_KEY, SECRET_KEY et API_URL

PARAMS = {
    "description": "New description",
    "environment": "1",
    "category": "server",
    "groups": [14]
}
ID = "44"

>>> CBWApi(API_URL, API_KEY, SECRET_KEY).update_server(ID, PARAMS)
# Voir la section Authentification pour la définition de la variable $client

PS> $Parameters = @{
    "description" = "New description"
    "environment" = "1"
    "category" = "server"
    "groups" = "[14]"
}
PS> $Id = 44

PS> $client.update_server($Id, $Parameters)

Retourne un objet contenant les champs suivants :

{
    "id": 74,
    "hostname": "2184acb15848",
    "addresses": ["127.0.0.1", "10.10.0.123", ],
    "description": "New description",
    "last_communication": "2019-10-30T10:20:13.000+01:00",
    "reboot_required": false,
    "updates_count": 1,
    "boot_at": "2019-10-09T08:52:46.000+02:00",
    "category": "server",
    "created_at": "2019-10-30T10:18:59.000+01:00",
    "analyzed_at": "2020-08-19T10:31:51.000+02:00",
    "cve_announcements_count": 4,
    "prioritized_cve_announcements_count": 1,
    "status": "server_update_comm_fail",
    "os": {
        "key": "ubuntu_1804_64",
        "name": "Ubuntu 18.04 LTS",
        "arch": "x86_64",
        "eol": "2023-04-26T02:00:00.000+02:00",
        "short_name": "Ubuntu 18.04",
        "type": "Os::Ubuntu"
    },
    "environment": {
        "id": 1,
        "name": "Low",
        "confidentiality_requirement": "confidentiality_requirement_low",
        "integrity_requirement": "integrity_requirement_low",
        "availability_requirement": "availability_requirement_low"
    },
    "groups": [
        {
            "id": 14,
            "name": "admin",
            "description": null,
            "color": "#12AFCB"
        }
    ],
    "compliance_repositories": [
        {
            "id": 1,
            "name": "CIS_Benchmark",
            "description": null,
            "color": "#336699"
        }
    ]
}

Point d'entrée permettant de modifier un actif existant.

Requête HTTP

PUT /api/v3/vulnerabilities/servers/<ID>

Paramètres de requête

Paramètres Description
ID
Obligatoire
ID de l'actif à modifier.

Permissions

Une clé d'API avec un niveau d'accès Complet est nécessaire.

Paramètres JSON

Paramètres Description
category
Optionnel
category à affecter au actif.
environment
Optionnel
environment à affecter à l'actif.
description
Optionnel
description à affecter à l'actif.
deploying_period
Optionnel
ID de la deploying_policy à ajouter à l'actif.
rebooting_period
Optionnel
ID de la rebooting_policy à ajouter à l'actif.
policy
Optionnel
ID de la politique d’analyse à attribuer à l'actif.
ignoring_policy
Optionnel
ID de la ignoring_policy à ajouter à l'actif.
groups
Optionnel
Liste d'ID de groups à affecter à l'actif. Ce paramètre remplace les groupes actuels de l'actif.

Suppression d'un actif

# Voir la section Authentification pour la définition des variables API_KEY, SECRET_KEY et API_URL

>>> CBWApi(API_URL, API_KEY, SECRET_KEY).delete_server("74")
# Voir la section Authentification pour la définition de la variable $client

PS> $client.delete_server("74")

Retourne un objet contenant les champs suivants :

{
    "id": 74,
    "hostname": "2184acb15848",
    "addresses": ["127.0.0.1", "10.10.0.123", ],
    "description": "New description",
    "last_communication": "2019-10-30T10:20:13.000+01:00",
    "reboot_required": false,
    "updates_count": 1,
    "boot_at": "2019-10-09T08:52:46.000+02:00",
    "category": "server",
    "created_at": "2019-10-30T10:18:59.000+01:00",
    "analyzed_at": "2020-08-19T10:31:51.000+02:00",
    "cve_announcements_count": 4,
    "prioritized_cve_announcements_count": 1,
    "status": "server_update_comm_fail",
    "os": {
        "key": "ubuntu_1804_64",
        "name": "Ubuntu 18.04 LTS",
        "arch": "x86_64",
        "eol": "2023-04-26T02:00:00.000+02:00",
        "short_name": "Ubuntu 18.04",
        "type": "Os::Ubuntu"
    },
    "environment": {
        "id": 2,
        "name": "Medium",
        "confidentiality_requirement": "confidentiality_requirement_medium",
        "integrity_requirement": "integrity_requirement_medium",
        "availability_requirement": "availability_requirement_medium"
    },
    "groups": [
        {
            "id": 14,
            "name": "admin",
            "description": null,
            "color": "#12AFCB"
        }
    ],
    "compliance_repositories": [
        {
            "id": 1,
            "name": "CIS_Benchmark",
            "description": null,
            "color": "#336699"
        }
    ]
}

Point d'entrée permettant de supprimer un actif.

Requête HTTP

DELETE /api/v3/vulnerabilities/servers/<ID>

Permissions

Une clé d'API avec un niveau d'accès Complet est nécessaire.

Paramètres de requête

Paramètres Description
ID
Obligatoire
ID de l'actif à supprimer.

Commenter une CVE d'un actif

# Voir la section Authentification pour la définition des variables API_KEY, SECRET_KEY et API_URL

PARAMS = {
    "comment": "update comment",
    "ignored": "false",
}

SERVER_ID = "102"

CVE_CODE = "CVE-2019-0752"

>>> CBWApi(API_URL, API_KEY, SECRET_KEY).update_server_cve(SERVER_ID, CVE_CODE, PARAMS)
# Voir la section Authentification pour la définition de la variable $client

PS> $Parameters = @{
    "comment" = "update comment"
    "ignored" = "false"
}

PS> $Cve_code = "CVE-2019-0752"

PS> $Server_id = "102"

PS> $client.update_server_cve($Server_id, $Cve_code, $Parameters)

Retourne un objet contenant les champs suivants :

{
    "id": 102,
    "hostname": "MSEDGEWIN10",
    "addresses": ["127.0.0.1", "10.10.0.123", ],
    "description": null,
    "last_communication": "2019-11-29T12:55:42.000+01:00",
    "reboot_required": false,
    "updates_count": 4,
    "boot_at": "2019-11-29T12:08:35.000+01:00",
    "category": "desktop",
    "created_at": "2019-11-29T12:10:27.000+01:00",
    "analyzed_at": "2020-08-19T10:31:51.000+02:00",
    "cve_announcements_count": 473,
    "prioritized_cve_announcements_count": 124,
    "status": "server_vulnerable",
    "cve_announcements": [
        {
            "cve_code": "CVE-2019-0732",
            "ignored": false,
            "comment": "comment",
            "active": false,
            "prioritized": false,
            "detected_at": "2019-11-29T12:10:27.000+01:00",
            "fixed_at": null
        },
        {
            "cve_code": "CVE-2019-0752",
            "ignored": false,
            "comment": "update comment",
            "prioritized": true,
            "detected_at": "2019-11-29T12:10:27.000+01:00",
            "fixed_at": null
        }, ...
    ],
    "updates": [
        {
            "id": 2544,
            "ignored": false,
            "patchable": true,
            "cve_announcements": [
                "CVE-2019-0732",
                "CVE-2019-0752",
                "CVE-2019-0895",
                ...
            ],
            "target": {
                "vendor": null,
                "product": "KB4523205",
                "type": "Packages::Kb",
                "version": "61118c04-b0ba-49af-82b7-05cb038923fb"
            },
            "current": null
        }, ...
    ],
    "os": {
        "key": "windows_10_1809_64",
        "name": "Windows 10 1809",
        "arch": "AMD64",
        "eol": "2021-05-11T00:00:00.000+02:00",
        "short_name": "Win 10 1809",
        "type": "Os::Windows"
    },
    "environment": {
        "id": 2,
        "name": "Medium",
        "confidentiality_requirement": "confidentiality_requirement_medium",
        "integrity_requirement": "integrity_requirement_medium",
        "availability_requirement": "availability_requirement_medium"
    },
    "groups": [],
    "compliance_repositories": []
}

Point d'entrée permettant d'ajouter un commentaire sur une CVE d'un actif.

Requête HTTP

PUT /api/v3/vulnerabilities/servers/<id>/cve_announcements/<cve_code>

Permissions

Une clé d'API avec un niveau d'accès Complet est nécessaire.

Paramètres de requête

Paramètres Description
id
Obligatoire
ID de l'actif pour lequel la CVE est à commenter.
cve_code
Obligatoire
Code de la CVE à commenter.

Paramètres JSON

Paramètres Description
comment
Optionnel
Commentaire à ajouter à la CVE de l'actif.
ignored
Optionnel
Status ignored à affecter à la CVE de l'actif.

Déployer les correctifs d'un actif

#Voir la section Authentification pour la définition des variables API_KEY, SECRET_KEY et API_URL

SERVER_ID = "104"

param = {
   "deploying_period_start":"16/01/2020 15:00",
   "updates_ids":["2554","2556"]
}

CLIENT.server_schedule_updates(SERVER_ID, param)
#Voir la section Authentification pour la définition de la variable $client

PS> $server_id="104"

PS> $Parameters=@{
    "deploying_period_start"="16/01/2020 15:00"
    "updates_ids"="2554,2556"
}

PS> $client.server_schedule_updates($server_id, $param)

Retourne un objet contenant les champs suivants :

{
    "id": 104,
    "hostname": "9627296e1c39",
    "addresses": ["127.0.0.1", "10.10.0.123", ],
    "description": null,
    "last_communication": "2020-01-16T13:18:02.000+01:00",
    "reboot_required": false,
    "updates_count": 4,
    "boot_at": "2020-01-15T08:52:54.000+01:00",
    "category": "server",
    "created_at": "2020-01-16T11:00:53.000+01:00",
    "analyzed_at": "2020-08-19T10:31:51.000+02:00",
    "cve_announcements_count": 12,
    "prioritized_cve_announcements_count": 4,
    "status": "server_vulnerable",
    "cve_announcements": [
        {
            "cve_code": "CVE-2018-8740",
            "ignored": false,
            "comment": null,
            "prioritized": false,
            "detected_at": "2020-01-16T11:00:53.000+01:00",
            "fixed_at": null
        }, ...
    ],
    "updates": [
        {
            "id": 2554,
            "ignored": false,
            "patchable": true,
            "cve_announcements": [
                "CVE-2018-8740",
                "CVE-2019-16168",
                "CVE-2019-19242",
                "CVE-2019-19244",
                "CVE-2019-5018",
                "CVE-2019-5827"
            ],
            "target": {
                "vendor": null,
                "product": "libsqlite3-0",
                "type": "Packages::Deb",
                "version": "3.22.0-1ubuntu0.2"
            },
            "current": {
                "vendor": null,
                "product": "libsqlite3-0",
                "type": "Packages::Deb",
                "version": "3.22.0-1ubuntu0.1"
            }
        }, ...
    ],
    "os": {
        "key": "ubuntu_1804_64",
        "name": "Ubuntu 18.04 LTS",
        "arch": "x86_64",
        "eol": "2023-04-26T02:00:00.000+02:00",
        "short_name": "Ubuntu 18.04",
        "type": "Os::Ubuntu"
    },
    "environment": {
        "id": 2,
        "name": "Medium",
        "confidentiality_requirement": "confidentiality_requirement_medium",
        "integrity_requirement": "integrity_requirement_medium",
        "availability_requirement": "availability_requirement_medium"
    },
    "groups": [
        {
            "id": 11,
            "name": "computers_factory",
            "description": null,
            "color": "#12AFCB",
            "created_at": "2019-09-17T11:27:49.000+02:00",
            "updated_at": "2019-09-17T11:27:49.000+02:00"
        }, ...
    ],
    "compliance_repositories": []
}

Point d'entrée permettant la planification du déploiement de correctifs d'un actif.

Requête HTTP

POST /api/v3/vulnerabilities/servers/<id>/updates

Permissions

Une clé d'API avec un niveau d'accès Complet est nécessaire.

Paramètres de requête

Paramètres Description
id
Obligatoire
ID de l'actif sur lequel déployer les correctifs.

Paramètres JSON

Paramètres Description
updates_ids
Obligatoire
IDs des correctifs à déployer.
deploying_period_start
Optionnel
Début de la période durant laquelle déployer les correctifs.

Redémarrer un actif

#Voir la section Authentification pour la définition des variables API_KEY, SECRET_KEY et API_URL

SERVER_ID = "104"

param = {
   "now":true
}

CLIENT.server_reboot(SERVER_ID, param)
#Voir la section Authentification pour la définition de la variable $client

PS> $server_id="104"

PS> $Parameters=@{
    "now"=True
}

PS> $client.server_reboot($server_id, $param)

Retourne un objet contenant les champs suivants :

{
    "addresses": [
        "10.0.2.15", ...
    ],
    "analyzed_at": "2021-06-30T17:56:07.000+02:00",
    "boot_at": "2021-06-30T15:38:21.000+02:00",
    "category": "server",
    "compliance_repositories": [],
    "created_at": "2021-06-30T15:40:00.000+02:00",
    "cve_announcements_count": 594,
    "description": null,
    "environment": {
        "availability_requirement": "availability_requirement_medium",
        "confidentiality_requirement": "confidentiality_requirement_medium",
        "id": 2,
        "integrity_requirement": "integrity_requirement_medium",
        "name": "Medium"
    },
    "groups": [],
    "hostname": "vagrant",
    "id": 21328,
    "last_communication": "2021-06-30T18:02:07.000+02:00",
    "os": {
        "arch": "x86_64",
        "eol": "2023-04-26T02:00:00.000+02:00",
        "key": "ubuntu_1804_64",
        "name": "Ubuntu 18.04 LTS",
        "short_name": "Ubuntu 18.04",
        "type": "Os::Ubuntu"
    },
    "prioritized_cve_announcements_count": 90,
    "reboot_required": false,
    "status": "server_vulnerable",
    "updates_count": 178
}

Point d'entrée permettant la planification du redémarrage d'un actif.

Requête HTTP

POST /api/v3/vulnerabilities/servers/<id>/reboot

Permissions

Une clé d'API avec un niveau d'accès Complet est nécessaire.

Paramètres de requête

Paramètres Description
id
Obligatoire
ID de l'actif à redémarrer.

Paramètres JSON

Paramètres Description
now
Optionnel
Planifier le script de redémarrage au plus tôt ou attendre la prochaine période de déploiement de l'actif.

Relancer les scripts d'analyse d'un actif

# Voir la section Authentification pour la définition des variables API_KEY, SECRET_KEY et API_URL

>>> CBWApi(API_URL, API_KEY, SECRET_KEY).refresh_server("7")
# Voir la section Authentification pour la définition de la variable $client

PS> $client.refresh_server("7")

Retourne un objet contenant les champs suivants :

{
  "id": 7,
  "hostname": "a5dfdabc8aeb",
  "addresses": ["127.0.0.1", "10.10.0.123", ],
  "description": "",
  "last_communication": "2020-05-12T10:58:02.000+02:00",
  "reboot_required": false,
  "updates_count": 22,
  "boot_at": "2020-05-11T08:40:06.000+02:00",
  "category": "server",
  "created_at": "2020-03-02T13:07:06.000+01:00",
  "analyzed_at": "2020-08-19T10:31:51.000+02:00",
  "cve_announcements_count": 58,
  "prioritized_cve_announcements_count": 17,
  "status": "server_vulnerable",
  "cve_announcements": [
    {
      "cve_code": "CVE-2018-8740",
      "ignored": false,
      "comment": null,
      "prioritized": false,
      "detected_at": "2020-03-02T13:07:06.000+01:00",
      "fixed_at": "2020-03-23T11:13:35.000+01:00"
    },
    ...
    {
      "cve_code": "CVE-2020-9383",
      "ignored": false,
      "comment": null,
      "prioritized": false,
      "detected_at": "2020-03-02T13:07:06.000+01:00",
      "fixed_at": null
    }
  ],
  "updates": [
    {
      "id": 368,
      "ignored": false,
      "patchable": true,
      "cve_announcements": [],
      "target": {
        "vendor": null,
        "product": "gcc-8-base",
        "type": "Packages::Deb",
        "version": "8.4.0-1ubuntu1~18.04"
      },
      "current": {
        "vendor": null,
        "product": "gcc-8-base",
        "type": "Packages::Deb",
        "version": "8.3.0-26ubuntu1~18.04"
      }
    },
    ...
    {
      "id": 810,
      "ignored": false,
      "patchable": true,
      "cve_announcements": [],
      "target": {
        "vendor": null,
        "product": "libldap-common",
        "type": "Packages::Deb",
        "version": "2.4.45+dfsg-1ubuntu1.5"
      },
      "current": {
        "vendor": null,
        "product": "libldap-common",
        "type": "Packages::Deb",
        "version": "2.4.45+dfsg-1ubuntu1.4"
      }
    }
  ],
  "os": {
    "key": "ubuntu_1804_64",
    "name": "Ubuntu 18.04 LTS",
    "arch": "x86_64",
    "eol": "2023-04-26T02:00:00.000+02:00",
    "short_name": "Ubuntu 18.04",
    "type": "Os::Ubuntu"
  },
  "environment": {
    "id": 2,
    "name": "Medium",
    "default": true,
    "confidentiality_requirement": "confidentiality_requirement_medium",
    "integrity_requirement": "integrity_requirement_medium",
    "availability_requirement": "availability_requirement_medium",
    "threshold": 0.0,
    "created_at": "2020-04-02T19:26:17.838+02:00",
    "updated_at": "2020-04-02T19:26:17.838+02:00"
  },
  "groups": [
    {
      "id": 16,
      "name": "computers_factory",
      "description": null,
      "color": "#12AFCB",
      "created_at": "2020-03-02T11:53:19.000+01:00",
      "updated_at": "2020-03-02T11:53:19.000+01:00"
    }
  ],
  "compliance_repositories": [],
  "security_issues": []
}

Point d'entrée permettant de relancer les scripts d'analyse d'un actif.

Requête HTTP

PUT /api/v3/vulnerabilities/servers/<id>/refresh

Permissions

Une clé d'API avec un niveau d'accès Complet est nécessaire.

Paramètres de requête

Paramètres Description
id
Obligatoire
ID de l'actif sur lequel relancer les scripts d'analyse.

CVE Announcements

Récupération de toutes les CVE

# Voir la section Authentification pour la définition des variables API_KEY, SECRET_KEY et API_URL

FILTERS = {"exploit_code_maturity": ["proof_of_concept"], "groups": ["admin"]}

>>> CBWApi(API_URL, API_KEY, SECRET_KEY).cve_announcements(FILTERS)
# Voir la section Authentification pour la définition de la variable $client

PS> $Filters = @{
    "exploit_code_maturity" = @("proof_of_concept")
    "groups" = @("admin")
}

PS> $client.cve_announcements($Filters)

Retourne un objet contenant les champs suivants :

[
    {
        "content": "The JFS file system code in Linux 2.4.x has an information leak in which in-memory data is written to the device for the JFS file system, which allows local users to obtain sensitive information by reading the raw device.",
        "cve_code": "CVE-2004-0181",
        "cvss": {
            "access_complexity": "access_complexity_low",
            "access_vector": "access_vector_local",
            "authentication": "authentication_none",
            "availability_impact": "availability_impact_none",
            "confidentiality_impact": "confidentiality_impact_partial",
            "integrity_impact": "integrity_impact_none"
        },
        "cvss_custom": null,
        "cvss_v3": null,
        "cwe": {
            "attacks": null,
            "capecs": null,
            "cwe_id": "NVD-CWE-Other"
        },
        "epss": 0.01282,
        "exploit_code_maturity": "unproven",
        "exploitable": false,
        "last_modified": "2017-10-11T03:29:00.000+02:00",
        "level": "level_low",
        "published": "2004-06-01T06:00:00.000+02:00",
        "score": 2.1,
        "score_custom": null,
        "score_v2": 2.1,
        "score_v3": null,
        "technologies": [
            {
                "product": "linux_kernel",
                "vendor": "linux"
            }
        ]
    }
    ...
]

Point d'entrée récupérant toutes les CVE.

Requête HTTP

GET /api/v3/vulnerabilities/cve_announcements

Permissions

Une clé d'API avec un niveau d'accès Lecture Seule est nécessaire.

Paramètres JSON

Paramètres Description
exploit_code_maturity
Optionnel
Filtre les CVE par exploit_code_maturity.
access_vector
Optionnel
Filtre les CVE par access_vector
active
Optionnel
Filtre les CVE par active.
level
Optionnel
Filtre les CVE par level.
ignored
Optionnel
Filtre les CVE par ignored.
prioritized
Optionnel
Filtre les CVE par prioritized.
technology_product
Optionnel
Filtre les CVE par technology_product.
technology_vendor
Optionnel
Filtre les CVE par technology_vendor.
groups
Optionnel
Filtres les CVE par une liste de groupes des actifs.
Pagination
Optionnel
Ce point d'entrée peut être paginé.

Récupérer une CVE spécifique

# Voir la section Authentification pour la définition des variables API_KEY, SECRET_KEY et API_URL

>>> CBWApi(API_URL, API_KEY, SECRET_KEY).cve_announcement("CVE-2019-3400")
# Voir la section Authentification pour la définition de la variable $client

PS> $client.cve_announcement("CVE-2019-3400")

Retourne un objet contenant les champs suivants :

{
    "content": "The labels gadget in Jira before version 7.13.2, and from version 8.0.0 before version 8.0.2 allows remote attackers to inject arbitrary HTML or JavaScript via a cross site scripting (XSS) vulnerability in the jql parameter.",
    "cve_code": "CVE-2019-3400",
    "cvss": {
        "access_complexity": "access_complexity_medium",
        "access_vector": "access_vector_network",
        "authentication": "authentication_none",
        "availability_impact": "availability_impact_none",
        "confidentiality_impact": "confidentiality_impact_none",
        "integrity_impact": "integrity_impact_partial"
    },
    "cvss_custom": null,
    "cvss_v3": {
        "attack_complexity": "attack_complexity_low",
        "attack_vector": "attack_vector_network",
        "availability_impact": "availability_impact_none",
        "confidentiality_impact": "confidentiality_impact_low",
        "integrity_impact": "integrity_impact_low",
        "privileges_required": "privileges_required_none",
        "scope": "scope_changed",
        "user_interaction": "user_interaction_required"
    },
    "cwe": {
        "attacks": [
            "TT1495",
            "TT1211",
            "TT1556"
        ],
        "capecs": [
            "CAPEC-209",
            "CAPEC-588",
            "CAPEC-591",
            "CAPEC-592",
            "CAPEC-63",
            "CAPEC-85"
        ],
        "cwe_id": "CWE-79"
    },
    "epss": 0.01055,
    "exploit_code_maturity": "functional",
    "exploitable": true,
    "last_modified": "2019-05-07T12:29:00.000+02:00",
    "level": "level_medium",
    "published": "2019-05-03T22:29:00.000+02:00",
    "score": 6.1,
    "score_custom": null,
    "score_v2": 4.3,
    "score_v3": 6.1,
    "security_announcements": [
        {
            "level": "level_unknown",
            "link": null,
            "sa_code": "CBW-2019-3400",
            "type": "SecurityAnnouncements::CbwWindows"
        },
        {
            "level": "level_unknown",
            "link": null,
            "sa_code": "CBWe-2019-3400",
            "type": "SecurityAnnouncements::CbwAppExclusive"
        }
    ],
    "servers": [
        {
            "active": true,
            "comment": null,
            "detected_at": "2020-10-06T10:10:18.000+02:00",
            "fixed_at": null,
            "hostname": "JIRA_7",
            "id": 964,
            "ignored": false,
            "os": null,
            "updates": [
                {
                    "current": {
                        "product": "JIRA Software 7.1.0",
                        "type": "Packages::WinApp",
                        "vendor": null,
                        "version": "7.1.0"
                    },
                    "id": 366611,
                    "ignored": false,
                    "patchable": false,
                    "target": {
                        "product": "jira",
                        "type": "Packages::WinApp",
                        "vendor": "atlassian",
                        "version": "8.9.1"
                    }
                }
            ],
            "prioritized": true
        },
      ...
    ],
    "technologies": [
        {
            "product": "jira",
            "vendor": "atlassian"
        }
    ]
}

Point d'entrée permettant de récupérer une CVE spécifique.

Requête HTTP

GET /api/v3/vulnerabilities/cve_announcements/<CVE_CODE>

Permissions

Une clé d'API avec un niveau d'accès Lecture Seule est nécessaire.

Paramètres de requête

Paramètres Description
CVE_CODE
Obligatoire
Code CVE de la CVE à récupérer

Personnalisation d'une CVE

# Voir la section Authentification pour la définition des variables API_KEY, SECRET_KEY et API_URL
PARAMETERS = {
    "score_custom": "7",
    "integrity_impact": "integrity_impact_none",
    "scope": "scope_unchanged"
}

CVE_CODE = "CVE-2019-20477"

>>> CBWApi(API_URL, API_KEY, SECRET_KEY).update_cve_announcement(CVE_CODE, PARAMETERS)
# Voir la section Authentification pour la définition de la variable $client
PS> $Parameters = @{
    "score_custom" = "7"
    "integrity_impact" = "integrity_impact_none"
    "scope" = "scope_unchanged"
}

PS> $client.update_cve_announcement("CVE-2019-20477", $Parameters)

Retourne un objet contenant les champs suivants :

{
    "content": "PyYAML 5.1 through 5.1.2 has insufficient restrictions on the load and load_all functions because of a class deserialization issue, e.g., Popen is a class in the subprocess module. NOTE: this issue exists because of an incomplete fix for CVE-2017-18342.",
    "cve_code": "CVE-2019-20477",
    "cvss": {
        "access_complexity": "access_complexity_low",
        "access_vector": "access_vector_network",
        "authentication": "authentication_none",
        "availability_impact": "availability_impact_partial",
        "confidentiality_impact": "confidentiality_impact_partial",
        "integrity_impact": "integrity_impact_partial"
    },
    "cvss_custom": {
        "attack_complexity": "attack_complexity_low",
        "attack_vector": "attack_vector_network",
        "availability_impact": "availability_impact_high",
        "confidentiality_impact": "confidentiality_impact_high",
        "integrity_impact": "integrity_impact_none",
        "privileges_required": "privileges_required_none",
        "scope": "scope_unchanged",
        "user_interaction": "user_interaction_none"
    },
    "cvss_v3": {
        "attack_complexity": "attack_complexity_low",
        "attack_vector": "attack_vector_network",
        "availability_impact": "availability_impact_high",
        "confidentiality_impact": "confidentiality_impact_high",
        "integrity_impact": "integrity_impact_high",
        "privileges_required": "privileges_required_none",
        "scope": "scope_unchanged",
        "user_interaction": "user_interaction_none"
    },
    "cwe": {
        "attacks": null,
        "capecs": [
            "CAPEC-586"
        ],
        "cwe_id": "CWE-502"
    },
    "epss": 0.01018,
    "exploit_code_maturity": "proof_of_concept",
    "exploitable": true,
    "last_modified": "2020-03-01T01:15:00.000+01:00",
    "level": "level_critical",
    "published": "2020-02-19T05:15:00.000+01:00",
    "score": 9.8,
    "score_custom": 7.0,
    "score_v2": 7.5,
    "score_v3": 9.8,
    "security_announcements": [
        {
            "level": "level_unknown",
            "link": "https://github.com/vmware/photon/wiki/Security-Updates-3.0-67",
            "sa_code": "PHSA-2020-3.0-0067",
            "type": "SecurityAnnouncements::PhotonOs"
        },
        ...
    ],
    "servers": [],
    "technologies": [
        {
            "product": "pyyaml",
            "vendor": "pyyaml_project"
        }
    ]
}

Point d'entrée permettant d'ajouter un score personnalisé ou une évaluation personnalisée de la criticité d'une vulnérabilité.
Quand un champ pour l'évaluation est donné, ceux qui sont omis sont automatiquement définis à la valeur maximale.

Requête HTTP

PUT /api/v3/vulnerabilities/cve_announcements/<cve_code>

Permissions

Une clé d'API avec un niveau d'accès Complet est nécessaire.

Paramètres de requête

Paramètres Description
cve_code
Obligatoire
Code CVE de la CVE à personnaliser.

Paramètres JSON

Paramètres Description
score_custom
Optionnel
Valeur du score personnalisé comprise entre 0.0 et 10.0.
attack_complexity
Optionnel
Valeur pour le champ Complexité d'Attaque de l'évaluation personnalisée.
Valeurs possibles :
  • attack_complexity_high
  • attack_complexity_low
attack_vector
Optionnel
Valeur pour le champ Vecteur d'Attaque de l'évaluation personnalisée.
Valeurs possibles :
  • attack_vector_adjacent
  • attack_vector_local
  • attack_vector_network
  • attack_vector_physical
availability_impact
Optionnel
Valeur pour le champ Impact de Disponibilité de l'évaluation personnalisée.
Valeurs possibles :
  • availability_impact_high
  • availability_impact_low
  • availability_impact_none
confidentiality_impact
Optionnel
Valeur pour le champ Impact de Confidentialité de l'évaluation personnalisée.
Valeurs possibles :
  • confidentiality_impact_high
  • confidentiality_impact_low
  • confidentiality_impact_none
integrity_impact
Optionnel
Valeur pour le champ Impact d'Integrité de l'évaluation personnalisée.
Valeurs possibles :
  • integrity_impact_high
  • integrity_impact_low
  • integrity_impact_none
privileges_required
Optionnel
Valeur pour le champ Privilèges Requis de l'évaluation personnalisée.
Valeurs possibles :
  • privileges_required_high
  • privileges_required_low
  • privileges_required_none
scope
Optionnel
Valeur pour le champ Portée de l'évaluation personnalisée.
Valeurs possibles :
  • scope_changed
  • scope_unchanged
user_interaction
Optionnel
Valeur pour le champ Interaction Utilisateur de l'évaluation personnalisée.
Valeurs possibles :
  • user_interaction_none
  • user_interaction_required

Suppression de la personnalisation d'une CVE

# Voir la section Authentification pour la définition des variables API_KEY, SECRET_KEY et API_URL
CVE_CODE = "CVE-2019-20477"
>>> CBWApi(API_URL, API_KEY, SECRET_KEY).delete_cve_announcement(CVE_CODE)
# Voir la section Authentification pour la définition de la variable $client
PS> $client.delete_cve_announcement("CVE-2019-20477")

Retourne un objet contenant les champs suivants :

{
    "content": "PyYAML 5.1 through 5.1.2 has insufficient restrictions on the load and load_all functions because of a class deserialization issue, e.g., Popen is a class in the subprocess module. NOTE: this issue exists because of an incomplete fix for CVE-2017-18342.",
    "cve_code": "CVE-2019-20477",
    "cvss": {
        "access_complexity": "access_complexity_low",
        "access_vector": "access_vector_network",
        "authentication": "authentication_none",
        "availability_impact": "availability_impact_partial",
        "confidentiality_impact": "confidentiality_impact_partial",
        "integrity_impact": "integrity_impact_partial"
    },
    "cvss_custom": null,
    "cvss_v3": {
        "attack_complexity": "attack_complexity_low",
        "attack_vector": "attack_vector_network",
        "availability_impact": "availability_impact_high",
        "confidentiality_impact": "confidentiality_impact_high",
        "integrity_impact": "integrity_impact_high",
        "privileges_required": "privileges_required_none",
        "scope": "scope_unchanged",
        "user_interaction": "user_interaction_none"
    },
    "cwe": {
        "attacks": null,
        "capecs": [
            "CAPEC-586"
        ],
        "cwe_id": "CWE-502"
    },
    "epss": 0.01018,
    "exploit_code_maturity": "proof_of_concept",
    "exploitable": true,
    "last_modified": "2020-03-01T01:15:00.000+01:00",
    "level": "level_critical",
    "published": "2020-02-19T05:15:00.000+01:00",
    "score": 9.8,
    "score_custom": null,
    "score_v2": 7.5,
    "score_v3": 9.8,
    "security_announcements": [],
    "servers": [],
    "technologies": [
        {
            "product": "pyyaml",
            "vendor": "pyyaml_project"
        }
    ]
}

Point d'entrée permettant de supprimer la personnalisation d'une vulnérabilité.

Requête HTTP

DELETE /api/v3/vulnerabilities/cve_announcements/<cve_code>

Permissions

Une clé d'API avec un niveau d'accès Complet est nécessaire.

Paramètres de requête

Paramètres Description
cve_code
Obligatoire
Code CVE de la CVE pour laquelle supprimer la personnalisation.

Défauts de sécurité

Récupération de tous les défauts de sécurité

# Voir la section Authentification pour la définition des variables API_KEY, SECRET_KEY et API_URL

>>> CBWApi(API_URL, API_KEY, SECRET_KEY).security_issues()
# Voir la section Authentification pour la définition de la variable $client

PS> $client.security_issues()

Retourne un objet contenant les champs suivants :

[
    {
        "description": "security issue description",
        "editable": false,
        "id": 1,
        "level": "level_info",
        "sid": "security_issue_01",
        "title": "SEC_ISSUE 01"
    }, ...
]

Point d'entrée permettant de récupérer tous les défauts de sécurité.

Requête HTTP

GET /api/v3/vulnerabilities/security_issues

Permissions

Une clé d'API avec un niveau d'accès Lecture Seule est nécessaire.

Paramètres de requête

Paramètres Description
level
Optionnel
Filtre les défauts de sécurité par level.
sid
Optionnel
Filtre les défauts de sécurité par sid.
Pagination
Optionnel
Ce point d'entrée peut être paginé.

Récupération d'un défaut de sécurité

# Voir la section Authentification pour la définition des variables API_KEY, SECRET_KEY et API_URL

>>> CBWApi(API_URL, API_KEY, SECRET_KEY).security_issue("1")
# Voir la section Authentification pour la définition de la variable $client

PS> $client.security_issue("1")

Retourne un objet contenant les champs suivants :

{
    "cve_announcements": [
        "CVE-2019-3400",
        "CVE-2018-20976"
    ],
    "description": "security issue description",
    "editable": false,
    "id": 1,
    "level": "level_info",
    "servers": [
        {
            "id": 10,
            "hostname": "ubuntu_18_04_01",
            "detected_at": "2021-08-31T16:19:36.209+02:00",
            "status": "active",
            "comment": null
        },
        {
            "id": 11,
            "hostname": "windows_10_01",
            "detected_at": "2021-08-31T16:19:36.209+02:00",
            "status": "ignored",
            "comment": "User comment."
        }
    ],
    "sid": "security_issue_01",
    "title": "SEC_ISSUE 01"
}

Point d'entrée permettant de récupérer un défaut de sécurité.

Requête HTTP

GET /api/v3/vulnerabilities/security_issues/<id>

Permissions

Une clé d'API avec un niveau d'accès Lecture Seule est nécessaire.

Paramètres de requête

Paramètres Description
id
Obligatoire
ID du défaut de sécurité à récupérer.

Création d'un défaut de sécurité

# Voir la section Authentification pour la définition des variables API_KEY, SECRET_KEY et API_URL

INFO = {
    "cve_announcements": [
        "CVE-2019-3400",
        "CVE-2018-20976"
    ],
    "description": "security issue description",
    "level": "level_info",
    "servers": [
        10,
        11
    ],
    "sid": "security_issue_01",
    "title": "SEC_ISSUE 01"
}

>>> CBWApi(API_URL, API_KEY, SECRET_KEY).create_security_issue(INFO)
# Voir la section Authentification pour la définition de la variable $client

PS> $Info = @{
    "cve_announcements" = @(
        "CVE-2019-3400",
        "CVE-2018-20976"
    )
    "description" = "security issue description"
    "level" = "level_info"
    "servers" = @(
        10,
        11
    )
    "sid" = "security_issue_01"
    "title" = "SEC_ISSUE 01"
}

PS> $client.create_security_issue($Info)

Retourne un objet contenant les champs suivants :

{
    "cve_announcements": [
        "CVE-2019-3400",
        "CVE-2018-20976"
    ],
    "description": "security issue description",
    "editable": true,
    "id": 1,
    "level": "level_info",
    "servers": [
        {
            "id": 10,
            "hostname": "ubuntu_18_04_01",
            "detected_at": "2021-08-31T16:19:36.209+02:00",
            "status": "active",
            "comment": null
        },
        {
            "id": 11,
            "hostname": "windows_10_01",
            "detected_at": "2021-08-31T16:19:36.209+02:00",
            "status": "active",
            "comment": null
        }
    ],
    "sid": "security_issue_01",
    "title": "SEC_ISSUE 01"
}

Point d'entrée créant un défaut de sécurité selon les paramètres donnés.

Requête HTTP

POST /api/v3/vulnerabilities/security_issues

Permissions

Une clé d'API avec un niveau d'accès Complet est nécessaire.

Paramètres JSON

Paramètres Description
sid
Obligatoire
SID du défaut de sécurité
cve_announcements
Optionnel
Liste de code de cve_announcements liées au défaut de sécurité.
description
Optionnel
Description du défaut de sécurité
level
Optionnel
Sévérité du défaut de sécurité
servers
Optionnel
Liste d'ID de servers affectée par le défaut de sécurité.
title
Optionnel
Titre du défaut de sécurité

Modification d'un défaut de sécurité

# Voir la section Authentification pour la définition des variables API_KEY, SECRET_KEY et API_URL

INFO = {"level": "level_info"}
ID = "1"

>>> CBWApi(API_URL, API_KEY, SECRET_KEY).update_security_issue(ID, INFO)
# Voir la section Authentification pour la définition de la variable $client

PS> $Info = @{"level" = "level_info"}
PS> $Id = 1

PS> $client.update_security_issue($Id, $Info)

Retourne un objet contenant les champs suivants :

{
    "cve_announcements": [
        "CVE-2019-3400",
        "CVE-2018-20976"
    ],
    "description": "security issue description",
    "editable": true,
    "id": 1,
    "level": "level_info",
    "servers": [
        {
            "id": 10,
            "hostname": "ubuntu_18_04_01",
            "detected_at": "2021-08-31T16:19:36.209+02:00",
            "status": "active",
            "comment": null
        },
        {
            "id": 11,
            "hostname": "windows_10_01",
            "detected_at": "2021-08-31T16:19:36.209+02:00",
            "status": "fixed",
            "comment": null
        }
    ],
    "sid": "security_issue_01",
    "title": "SEC_ISSUE 01"
}

Point d'entrée permettant de modifier un défaut de sécurité existant.

Requête HTTP

PUT /api/v3/vulnerabilities/security_issues/<id>

Permissions

Paramètres de requête

Paramètres Description
id
Obligatoire
ID du défaut de sécurité à modifier.

Paramètres JSON

Paramètres Description
cve_announcements
Optionnel
Liste de code de cve_announcements liées au défaut de sécurité.
description
Optionnel
Description du défaut de sécurité
level
Optionnel
Sévérité du défaut de sécurité
servers
Optionnel
Liste d'ID de servers affectée par le défaut de sécurité.
sid
Optionnel
SID du défaut de sécurité
title
Optionnel
Titre du défaut de sécurité

Suppression d'un défaut de sécurité

# Voir la section Authentification pour la définition des variables API_KEY, SECRET_KEY et API_URL

>>> CBWApi(API_URL, API_KEY, SECRET_KEY).delete_security_issue("1")
# Voir la section Authentification pour la définition de la variable $client

PS> $client.delete_security_issue("1")

Retourne un objet contenant les champs suivants :

{
    "cve_announcements": [
        "CVE-2019-3400",
        "CVE-2018-20976"
    ],
    "description": "security issue description",
    "editable": true,
    "id": 1,
    "level": "level_info",
    "servers": [
        {
            "id": 10,
            "hostname": "ubuntu_18_04_01",
            "detected_at": "2021-08-31T16:19:36.209+02:00",
            "status": "active",
            "comment": null
        },
        {
            "id": 11,
            "hostname": "windows_10_01",
            "detected_at": "2021-08-31T16:19:36.209+02:00",
            "status": "active",
            "comment": null
        }
    ],
    "sid": "security_issue_01",
    "title": "SEC_ISSUE 01"
}

Point d'entrée permettant de supprimer un défaut de sécurité.

Requête HTTP

DELETE /api/v3/vulnerabilities/security_issues/<id>

Permissions

Paramètres de requête

Paramètres Description
id
Obligatoire
ID du défaut de sécurité à supprimer.

Gestion des conformités

Actifs (conformité)

Récupération de tous les actifs de conformité

# Voir la section Authentification pour la définition des variables API_KEY, SECRET_KEY et API_URL

>>> CBWApi(API_URL, API_KEY, SECRET_KEY).compliance_servers()
# Voir la section Authentification pour la définition de la variable $client

PS> $client.compliance_servers()

Retourne un objet contenant les champs suivants :

[
    {
        "boot_at": "2020-09-08T10:04:43.000+02:00",
        "category": "server",
        "compliance_repositories": [
            {
                "color": "#336699",
                "created_at": "2020-09-07T14:35:51.000+02:00",
                "description": null,
                "id": 1,
                "name": "Security Best Practices",
                "updated_at": "2020-09-07T14:35:51.000+02:00"
            }
        ],
        "compliance_rules_count": 11,
        "compliance_rules_failed_count": 2,
        "compliance_rules_succeed_count": 9,
        "created_at": "2020-09-08T11:10:57.000+02:00",
        "description": "",
        "environment": {
            "availability_requirement": "availability_requirement_medium",
            "confidentiality_requirement": "confidentiality_requirement_medium",
            "created_at": "2020-09-04T17:10:18.309+02:00",
            "default": true,
            "id": 2,
            "integrity_requirement": "integrity_requirement_medium",
            "name": "Medium",
            "threshold": 7.5,
            "updated_at": "2020-09-04T17:10:18.309+02:00"
        },
        "groups": [
            {
                "color": "#12AFCB",
                "created_at": "2020-09-11T15:55:00.000+02:00",
                "description": null,
                "id": 12,
                "name": "admin",
                "updated_at": "2020-09-11T15:55:00.000+02:00"
            }
        ],
        "hostname": "2184acb15848",
        "id": 1,
        "last_communication": "2020-09-13T16:26:01.000+02:00",
        "os": {
            "arch": "x86_64",
            "eol": "2025-04-01T02:00:00.000+02:00",
            "key": "ubuntu_2004_64",
            "name": "Ubuntu 20.04 LTS",
            "short_name": "Ubuntu 20.04",
            "type": "Os::Ubuntu"
        },
        "reboot_required": false,
        "status": "cbw_compliance_server_compliant"
    }, ...
]

Point d'entrée permettant de récupérer tous les Actifs.

Requête HTTP

GET /api/v3/compliance/servers

Permissions

Une clé d'API avec un niveau d'accès Lecture Seule est nécessaire.

Récupération d'un actif de conformité

# Voir la section Authentification pour la définition des variables API_KEY, SECRET_KEY et API_URL

>>> CBWApi(API_URL, API_KEY, SECRET_KEY).compliance_server("102")
# Voir la section Authentification pour la définition de la variable $client

PS> $client.compliance_server("102")

Retourne un objet contenant les champs suivants :

{
    "boot_at": "2020-09-08T10:04:43.000+02:00",
    "category": "server",
    "compliance_repositories": [
        {
            "color": "#cb2212",
            "created_at": "2020-09-11T15:43:24.000+02:00",
            "description": null,
            "id": 11,
            "name": "Security Best Practices",
            "updated_at": "2020-09-11T15:43:24.000+02:00"
        }
    ],
    "compliance_rules_count": 11,
    "compliance_rules_failed_count": 2,
    "compliance_rules_succeed_count": 9,
    "created_at": "2020-09-08T11:10:57.000+02:00",
    "description": "",
    "environment": {
        "availability_requirement": "availability_requirement_medium",
        "confidentiality_requirement": "confidentiality_requirement_medium",
        "created_at": "2020-09-04T17:10:18.309+02:00",
        "default": true,
        "id": 2,
        "integrity_requirement": "integrity_requirement_medium",
        "name": "Medium",
        "threshold": 7.5,
        "updated_at": "2020-09-04T17:10:18.309+02:00"
    },
    "groups": [
        {
            "color": "#12AFCB",
            "created_at": "2020-09-11T15:55:00.000+02:00",
            "description": null,
            "id": 12,
            "name": "admin",
            "updated_at": "2020-09-11T15:55:00.000+02:00"
        }
    ],
    "hostname": "2184acb15848",
    "id": 1,
    "last_communication": "2020-09-12T13:56:01.000+02:00",
    "os": {
        "arch": "x86_64",
        "eol": "2025-04-01T02:00:00.000+02:00",
        "key": "ubuntu_2004_64",
        "name": "Ubuntu 20.04 LTS",
        "short_name": "Ubuntu 20.04",
        "type": "Os::Ubuntu"
    },
    "reboot_required": false,
    "rules": [
        {
            "code": "SBP-LIN-04-006",
            "id": 4900,
            "last_verification": "2020-09-11T16:57:26.000+02:00",
            "status": "cbw_compliance_script_success"
        },
        {
            "code": "SBP-LIN-04-004",
            "id": 4906,
            "last_verification": "2020-09-11T16:57:26.000+02:00",
            "status": "cbw_compliance_script_success"
        }
    ],
    "status": "cbw_compliance_server_compliant"
}

Point d'entrée permettant de récupérer un actif.

Requête HTTP

GET /api/v3/compliance/servers/<ID>

Permissions

Une clé d'API avec un niveau d'accès Lecture Seule est nécessaire.

Paramètres de requête

Paramètres Description
ID
Obligatoire
ID de l'actif à récupérer.

Exporter un actif Conformité

Retourne un objet contenant les champs suivants :

HOSTNAME:2184acb15848
REPOSITORY:Security Best Practices

--cbw-compliance-check
Rule: SBP-LIN-04-006
Check: 1

…

Exporte les données de conformité d’un actif pour archivage ou import ultérieur.

Requête HTTP

GET /api/v3/compliance/servers/<ID>/export

Permissions

Une clé d'API avec un niveau d'accès Lecture Seule est nécessaire.

Paramètres de requête

Paramètres Description
ID
Obligatoire
ID de l'actif à exporter.

Modification d'un actif de conformité existant

# Voir la section Authentification pour la définition des variables API_KEY, SECRET_KEY et API_URL

PARAMS = {"compliance_repositories": [9]}
ID = "82"

>>> CBWApi(API_URL, API_KEY, SECRET_KEY).update_compliance_server(ID, PARAMS)
# Voir la section Authentification pour la définition de la variable $client

PS> $Parameters = @{"compliance_repositories" = "[9]"}
PS> $Id = 82

PS> $client.update_compliance_server($Id, $Parameters)

Retourne un objet contenant les champs suivants :

{
    "boot_at": null,
    "category": "desktop",
    "compliance_repositories": [
        {
            "color": "#336699",
            "created_at": "2020-10-23T11:21:15.000+02:00",
            "description": null,
            "id": 9,
            "name": "Security_Best_Practices",
            "updated_at": "2020-10-23T11:21:15.000+02:00"
        }
    ],
    "compliance_rules_count": 0,
    "compliance_rules_failed_count": 0,
    "compliance_rules_succeed_count": 0,
    "created_at": "2020-10-23T11:13:52.000+02:00",
    "description": null,
    "environment": {
        "availability_requirement": "availability_requirement_medium",
        "confidentiality_requirement": "confidentiality_requirement_medium",
        "created_at": "2020-10-19T09:37:24.541+02:00",
        "default": true,
        "id": 2,
        "integrity_requirement": "integrity_requirement_medium",
        "name": "Medium",
        "threshold": 7.5,
        "updated_at": "2020-10-19T09:37:24.541+02:00"
    },
    "groups": [],
    "hostname": "windows_7_02",
    "id": 82,
    "last_communication": "2020-10-23T11:13:54.000+02:00",
    "os": {
        "arch": null,
        "eol": "2020-01-14T01:00:00.000+01:00",
        "key": "windows_7",
        "name": "Windows 7",
        "short_name": "Win 7",
        "type": "Os::Windows"
    },
    "reboot_required": false,
    "status": "gen_idle"
}

Point d'entrée permettant de modifier un actif existant.

Requête HTTP

PUT /api/v3/compliance/servers/<ID>

Permissions

Une clé d'API avec un niveau d'accès Complet est nécessaire.

Paramètres de requête

Paramètres Description
id
Obligatoire
ID de l'actif à modifier.

Paramètres JSON

Paramètres Description
compliance_repositories
Optionnel
Liste d'ID de compliance_repositories à ajouter à l'actif. Ce paramètre remplace les compliance_repositories actuels de l'actif

Relancer les règles de conformités d'un actif

# Voir la section Authentification pour la définition des variables API_KEY, SECRET_KEY et API_URL

>>> CBWApi(API_URL, API_KEY, SECRET_KEY).recheck_rules("1")
# Voir la section Authentification pour la définition de la variable $client

PS> $client.recheck_rules("1")

Retourne un objet contenant les champs suivants :

{
    "boot_at": "2020-09-08T10:04:43.000+02:00",
    "category": "server",
    "compliance_repositories": [
        {
            "color": "#cb2212",
            "created_at": "2020-09-11T15:43:24.000+02:00",
            "description": null,
            "id": 11,
            "name": "Security Best Practices",
            "updated_at": "2020-09-11T15:43:24.000+02:00"
        }
    ],
    "compliance_rules_count": 11,
    "compliance_rules_failed_count": 2,
    "compliance_rules_succeed_count": 9,
    "created_at": "2020-09-08T11:10:57.000+02:00",
    "description": "",
    "environment": {
        "availability_requirement": "availability_requirement_medium",
        "confidentiality_requirement": "confidentiality_requirement_medium",
        "created_at": "2020-09-04T17:10:18.309+02:00",
        "default": true,
        "id": 2,
        "integrity_requirement": "integrity_requirement_medium",
        "name": "Medium",
        "threshold": 7.5,
        "updated_at": "2020-09-04T17:10:18.309+02:00"
    },
    "groups": [
        {
            "color": "#12AFCB",
            "created_at": "2020-09-11T15:55:00.000+02:00",
            "description": null,
            "id": 12,
            "name": "admin",
            "updated_at": "2020-09-11T15:55:00.000+02:00"
        }
    ],
    "hostname": "2184acb15848",
    "id": 1,
    "last_communication": "2020-09-12T13:56:01.000+02:00",
    "os": {
        "arch": "x86_64",
        "eol": "2025-04-01T02:00:00.000+02:00",
        "key": "ubuntu_2004_64",
        "name": "Ubuntu 20.04 LTS",
        "short_name": "Ubuntu 20.04",
        "type": "Os::Ubuntu"
    },
    "reboot_required": false,
    "rules": [
        {
            "code": "SBP-LIN-04-006",
            "id": 4900,
            "last_verification": "2020-09-11T16:57:26.000+02:00",
            "status": "cbw_compliance_script_success"
        },
        {
            "code": "SBP-LIN-04-004",
            "id": 4906,
            "last_verification": "2020-09-11T16:57:26.000+02:00",
            "status": "cbw_compliance_script_success"
        }
    ],
    "status": "cbw_compliance_server_compliant"
}

Point d'entrée permettant de relancer les règles de conformités d'un actif.

Requête HTTP

POST /api/v3/compliance/servers/<id>/recheck_rules

Permissions

Une clé d'API avec un niveau d'accès Complet est nécessaire.

Paramètres de requête

Paramètres Description
id
Obligatoire
ID de l'actif sur lequel relancer les règles de conformités.

Règles de conformité

Récupération de toutes les règles de conformités

# Voir la section Authentification pour la définition des variables API_KEY, SECRET_KEY et API_URL

FILTERS = {"repositories": ["CIS_Benchmark", "Security_Best_Practices"],
           "level": "medium", "os": "ubuntu_2004_64"}

>>> CBWApi(API_URL, API_KEY, SECRET_KEY).compliance_rules(FILTERS)
# Voir la section Authentification pour la définition de la variable $client

PS> $Filters = @{
    repositories = "CIS_Benchmark", "Security_Best_Practices"
    level = "medium"
    os = "ubuntu_2004_64"
}

PS> $client.compliance_rules($Filters)

Retourne un objet contenant les champs suivants :

[
    {
        "audit": "Run the following command and ensure output is in compliance with site policy:\n<pre>\n# grep max_log_file /etc/audit/auditd.conf\nmax_log_file = &lt;MB&gt;\n</pre>",
        "checks": [
            {
                "content": "# Check if the next command has returns\ngrep max_log_file /etc/audit/auditd.conf || true\n",
                "failure": ".*",
                "order": 1,
                "success": "max_log_file|/etc/audit/auditd.conf",
                "type": "CbwCompliance::Checks::WithScript"
            }
        ],
        "code": "CIS-linux-4.1.1.1",
        "created_at": "2019-06-19T08:52:05.000+02:00",
        "description": "Configure the maximum size of the audit log file. Once the log reaches the maximum size, it will be rotated and a new log file will be started.",
        "equation": "1",
        "id": 296,
        "last_modified_at": "2020-07-02T11:47:09.000+02:00",
        "level": "medium",
        "name": "Ensure audit log storage size is configured",
        "os": [
            {
                "key": "ubuntu_2004_64"
            }, ...
        ],
        "published_at": "2019-06-19T08:52:05.000+02:00",
        "rationale": "It is important that an appropriate size is determined for log files so that they do not impact the system and audit data is not lost.",
        "reference": "4.1.1.1",
        "remediation": "Set the following parameter in /etc/audit/auditd.conf in accordance with site policy: <pre> max_log_file = &lt;MB&gt; </pre>",
        "require_sudo": true,
        "repositories": [
            {
                "color": "#336699",
                "description": null,
                "id": 1,
                "name": "CIS_Benchmark"
            }, ...
        ],
        "type": null,
        "updated_at": "2020-10-23T10:59:07.000+02:00"
    }, ...
]

Point d'entrée permettant de récupérer toutes les règles de conformités.

Requête HTTP

GET /api/v3/compliance/rules

Permissions

Une clé d'API avec un niveau d'accès Lecture Seule est nécessaire.

Paramètres JSON

Paramètres Description
codes
Optionnel
Filtre les règles de conformité avec une lists de codes.
level
Optionnel
Filtre les règles de conformité par level.
os
Optionnel
Filtre les règles de conformité par os.
repositories
Optionnel
Filtre les règles de conformité avec une lists de repositories.
type
Optionnel
Filtre les règles de conformité par type.
Pagination
Optionnel
Ce point d'entrée peut être paginé.

Récupération d'une règle de conformité

# Voir la section Authentification pour la définition des variables API_KEY, SECRET_KEY et API_URL

>>> CBWApi(API_URL, API_KEY, SECRET_KEY).compliance_rule("4936")
# Voir la section Authentification pour la définition de la variable $client

PS> $client.compliance_rule("4936")

Retourne un objet contenant les champs suivants :

{
    "audit": "Ensure at least one file named /etc/hosts.deny exists and is owned by 0:0 and has permissions rw-r--r-- and does not have permissions --x-wx-wx SUID SGID sticky",
    "checks": [
        {
            "content": "# Ensure at least one file named /etc/hosts.deny exists and is owned by 0:0 and has permissions rw-r--r-- and does not have permissions --x-wx-wx SUID SGID sticky\nstat -c '%A:%u:%g' '/etc/hosts.deny'\n",
            "failure": "stat|(.)?[\\w-]{9}:\\d:\\d",
            "order": 1,
            "success": "(.)?rw-r--r--:0:0",
            "type": "CbwCompliance::Checks::WithScript"
        }
    ],
    "code": "SBP-LIN-04-007",
    "created_at": "2020-07-02T11:44:04.000+02:00",
    "description": "The /etc/hosts.deny file contains network information that is used by many system applications and therefore must be readable for these applications to operate.",
    "equation": "1",
    "id": 4936,
    "last_modified_at": "2020-07-02T11:44:04.000+02:00",
    "level": "minimal",
    "name": "Ensure permissions on /etc/hosts.deny are configured",
    "os": [
        {
            "key": "ubuntu_1604_64"
        },
        {
            "key": "ubuntu_1804_64"
        },
        {
            "key": "ubuntu_2004_64"
        }
    ],
    "published_at": "2020-07-02T11:44:04.000+02:00",
    "rationale": "It is critical to ensure that the /etc/hosts.deny file is protected from unauthorized write access. Although it is protected by default, the file permissions could be changed either inadvertently or through malicious actions.",
    "reference": null,
    "remediation": "Run the following commands to set permissions on /etc/hosts.deny :\n\n<pre># chown root:root /etc/hosts.deny# chmod 644 /etc/hosts.deny</pre>",
    "require_sudo": true,
    "repositories": [
        {
            "name": "Security_Best_Practices"
        }
    ],
    "servers": [
        {
            "hostname": "heracles",
            "id": 1,
            "last_verification": "2020-09-13T22:26:14.000+02:00",
            "status": "gen_idle"
        }
    ],
    "type": null,
    "updated_at": "2020-09-11T15:38:52.000+02:00"
}

Point d'entrée permettant de récupérer une règle de conformité.

Requête HTTP

GET /api/v3/compliance/rules/<id>

Permissions

Une clé d'API avec un niveau d'accès Lecture Seule est nécessaire.

Paramètres de requête

Paramètres Description
id
Obligatoire
ID de la règle de conformité à récupérer.

Création d'une règle de conformité

# Voir la section Authentification pour la définition des variables API_KEY, SECRET_KEY et API_URL
INFO = {
"audit": "Verify cron is enabled",
"code": "SBP-Custom-001-cron",
"description": "The cron daemon is used to execute batch jobs on the system.",
"equation": "(1 && 2)",
"name": "Ensure cron daemon is enabled",
"rationale": "While there may not be user jobs that need to be run on the system, the system does have maintenance jobs that may include security monitoring that have to run, and cron is used to execute them.",
"remediation": "systemctl --now enable cron",
"checks": [
        {
            "order": 1,
            "content": "systemctl is-enabled cron",
            "success": "enabled",
            "failure": "disabled"
        },
        {
            "order": 2,
            "content": "service cron status",
            "success": "active",
            "failure": "disabled"
        }
    ],
    "os": ["ubuntu_2004_64"]
}

>>> CBWApi(API_URL, API_KEY, SECRET_KEY).create_compliance_rule(INFO)
# Voir la section Authentification pour la définition de la variable $client

PS> $Info = @{
"audit" = "Verify cron is enabled"
"code" = "SBP-Custom-001-cron"
"description" = "The cron daemon is used to execute batch jobs on the system."
"equation" = "(1 && 2)"
"name" = "Ensure cron daemon is enabled"
"rationale" = "While there may not be user jobs that need to be run on the system the system does have maintenance jobs that may include security monitoring that have to run and cron is used to execute them."
"remediation" = "systemctl --now enable cron"
"checks" = @(
        @{
            "order" = 1
            "content" = "systemctl is-enabled cron"
            "success" = "enabled"
            "failure" = "disabled"
        },
        @{
            "order" = 2
            "content" = "service cron status"
            "success" = "active"
            "failure" = "disabled"
        }
    )
"os" = @("ubuntu_2004_64")
}

PS> $client.create_compliance_rule($Info)

Retourne un objet contenant les champs suivants :

{
    "audit": "Verify cron is enabled",
    "checks": [
        {
            "content": "systemctl is-enabled cron",
            "failure": "disabled",
            "order": 1,
            "success": "enabled",
            "type": "CbwCompliance::Checks::WithScript"
        },
        {
            "content": "service cron status",
            "failure": "disabled",
            "order": 2,
            "success": "active",
            "type": "CbwCompliance::Checks::WithScript"
        }
    ],
    "code": "SBP-Custom-001-cron",
    "created_at": "2020-07-02T11:44:04.000+02:00",
    "description": "The cron daemon is used to execute batch jobs on the system.",
    "equation": "(1 && 2)",
    "id": 5000,
    "last_modified_at": "2020-07-02T11:44:04.000+02:00",
    "level": "minimal",
    "name": "Ensure cron daemon is enabled",
    "os": [
        {
            "key": "ubuntu_2004_64"
        }
    ],
    "published_at": "2020-07-02T11:44:04.000+02:00",
    "rationale": "While there may not be user jobs that need to be run on the system, the system does have maintenance jobs that may include security monitoring that have to run, and cron is used to execute them.",
    "reference": null,
    "remediation": "systemctl --now enable cron",
    "require_sudo": false,
    "repositories": [],
    "servers": [],
    "type": null,
    "updated_at": "2020-09-11T15:38:52.000+02:00"
}

Point d'entrée créant une règle de conformité selon les paramètres donnés.

Requête HTTP

POST /api/v3/compliance/rules

Permissions

Une clé d'API avec un niveau d'accès Complet est nécessaire.

Paramètres JSON

Paramètres Description
audit
Obligatoire
Audit de la règle de conformité
checks
Obligatoire
Liste des checks à ajouter à la règle de conformité.
Champs requis :
  • Contenu de la vérification (script à exécuter)
  • Expression régulière de non conformité
  • Ordre de la vérification
  • Expression régulière de conformité
code
Obligatoire
Code de la règle de conformité
description
Obligatoire
Description de la règle de conformité
equation
Obligatoire
Equation des vérification de la règle de conformité
name
Obligatoire
Nom de la règle de conformité
os
Obligatoire
Liste des os à ajouter à la règle de conformité
rationale
Obligatoire
Objectif de la règle de conformité
remediation
Obligatoire
Remédiation de la règle de conformité
level
Optionnel
Niveau de la règle de conformité
reference
Optionnel
Niveau de la règle de conformité
require_sudo
Optionnel
Niveau de la règle de conformité
repositories
Optionnel
Liste des repositories à ajouter à la règle de conformité

Modification d'une règle de conformité

# Voir la section Authentification pour la définition des variables API_KEY, SECRET_KEY et API_URL

INFO = {"audit": "New audit for this rule"}
ID = "1"

>>> CBWApi(API_URL, API_KEY, SECRET_KEY).update_compliance_rule(ID, INFO)
# Voir la section Authentification pour la définition de la variable $client

PS> $Info = @{"audit" = "New audit for this rule"}
PS> $Id = 1

PS> $client.update_compliance_rule($Id, $Info)

Retourne un objet contenant les champs suivants :

{
    "audit": "New audit for this rule",
    "checks": [
        {
            "content": "rule content",
            "failure": "regex failure",
            "order": 1,
            "success": "regex success",
            "type": "CbwCompliance::Checks::WithScript"
        },
        {
            "content": "rule content",
            "failure": "regex failure",
            "order": 2,
            "success": "regex success",
            "type": "CbwCompliance::Checks::WithScript"
        }
    ],
    "code": "SBP-Custom-001",
    "created_at": "2020-07-02T11:44:04.000+02:00",
    "description": "rule description",
    "equation": "(1 && 2)",
    "id": 5000,
    "last_modified_at": "2020-07-02T11:44:04.000+02:00",
    "level": "minimal",
    "name": "rule name",
    "os": [
        {
            "key": "ubuntu_2004_64"
        }
    ],
    "published_at": "2020-07-02T11:44:04.000+02:00",
    "rationale": "rule rationale",
    "reference": null,
    "remediation": "rule remediation",
    "require_sudo": false,
    "repositories": [],
    "servers": [],
    "type": null,
    "updated_at": "2020-09-11T15:38:52.000+02:00"
}

Point d'entrée permettant de modifier une règle de conformité existante.

Requête HTTP

PUT /api/v3/compliance/rules/<id>

Permissions

Une clé d'API avec un niveau d'accès Complet est nécessaire.

Paramètres de requête

Paramètres Description
id
Obligatoire
ID de la règle de conformité à modifier.

Paramètres JSON

Paramètres Description
audit
Optionnel
Audit de la règle de conformité
checks
Optionnel
Liste des checks à ajouter à la règle de conformité.
Champs requis :
  • Contenu de la vérification (script à exécuter)
  • Expression régulière de non conformité
  • Ordre de la vérification
  • Expression régulière de conformité
code
Optionnel
Code de la règle de conformité
description
Optionnel
Description de la règle de conformité
equation
Optionnel
Equation des vérification de la règle de conformité
level
Optionnel
Niveau de la règle de conformité
name
Optionnel
Nom de la règle de conformité
os
Optionnel
Liste des os à ajouter à la règle de conformité
rationale
Optionnel
Objectif de la règle de conformité
reference
Optionnel
Niveau de la règle de conformité
remediation
Optionnel
Remédiation de la règle de conformité
require_sudo
Optionnel
Niveau de la règle de conformité
repositories
Optionnel
Liste des repositories à ajouter à la règle de conformité

Suppression d'une règle de conformité

# Voir la section Authentification pour la définition des variables API_KEY, SECRET_KEY et API_URL

>>> CBWApi(API_URL, API_KEY, SECRET_KEY).delete_compliance_rule("4936")
# Voir la section Authentification pour la définition de la variable $client

PS> $client.delete_compliance_rule("4936")

Retourne un objet contenant les champs suivants :

{
    "audit": "Ensure at least one file named /etc/hosts.deny exists and is owned by 0:0 and has permissions rw-r--r-- and does not have permissions --x-wx-wx SUID SGID sticky",
    "checks": [
        {
            "content": "# Ensure at least one file named /etc/hosts.deny exists and is owned by 0:0 and has permissions rw-r--r-- and does not have permissions --x-wx-wx SUID SGID sticky\nstat -c '%A:%u:%g' '/etc/hosts.deny'\n",
            "failure": "stat|(.)?[\\w-]{9}:\\d:\\d",
            "order": 1,
            "success": "(.)?rw-r--r--:0:0",
            "type": "CbwCompliance::Checks::WithScript"
        }
    ],
    "code": "SBP-LIN-04-007",
    "created_at": "2020-07-02T11:44:04.000+02:00",
    "description": "The /etc/hosts.deny file contains network information that is used by many system applications and therefore must be readable for these applications to operate.",
    "equation": "1",
    "id": 4936,
    "last_modified_at": "2020-07-02T11:44:04.000+02:00",
    "level": "minimal",
    "name": "Ensure permissions on /etc/hosts.deny are configured",
    "os": [
        {
            "key": "ubuntu_1604_64"
        },
        {
            "key": "ubuntu_1804_64"
        },
        {
            "key": "ubuntu_2004_64"
        }
    ],
    "published_at": "2020-07-02T11:44:04.000+02:00",
    "rationale": "It is critical to ensure that the /etc/hosts.deny file is protected from unauthorized write access. Although it is protected by default, the file permissions could be changed either inadvertently or through malicious actions.",
    "reference": null,
    "remediation": "Run the following commands to set permissions on /etc/hosts.deny :\n\n<pre># chown root:root /etc/hosts.deny# chmod 644 /etc/hosts.deny</pre>",
    "require_sudo": true,
    "repositories": [
        {
            "name": "Security_Best_Practices"
        }
    ],
    "servers": [
        {
            "hostname": "heracles",
            "id": 1,
            "last_verification": "2020-09-13T22:26:14.000+02:00",
            "status": "gen_idle"
        }
    ],
    "type": null,
    "updated_at": "2020-09-11T15:38:52.000+02:00"
}

Point d'entrée permettant de supprimer une règle de conformité.

Requête HTTP

DELETE /api/v3/compliance/rules/<id>

Permissions

Une clé d'API avec un niveau d'accès Complet est nécessaire.

Paramètres de requête

Paramètres Description
id
Obligatoire
ID de la règle de conformité à supprimer.

Relancer la règle de conformité sur tous les actifs associés

# Voir la section Authentification pour la définition des variables API_KEY, SECRET_KEY et API_URL

>>> CBWApi(API_URL, API_KEY, SECRET_KEY).recheck_servers("1")
# Voir la section Authentification pour la définition de la variable $client

PS> $client.recheck_servers("1")

Retourne un objet contenant les champs suivants :

{
    "audit": "Ensure at least one file named /etc/hosts.deny exists and is owned by 0:0 and has permissions rw-r--r-- and does not have permissions --x-wx-wx SUID SGID sticky",
    "checks": [
        {
            "content": "# Ensure at least one file named /etc/hosts.deny exists and is owned by 0:0 and has permissions rw-r--r-- and does not have permissions --x-wx-wx SUID SGID sticky\nstat -c '%A:%u:%g' '/etc/hosts.deny'\n",
            "failure": "stat|(.)?[\\w-]{9}:\\d:\\d",
            "order": 1,
            "success": "(.)?rw-r--r--:0:0",
            "type": "CbwCompliance::Checks::WithScript"
        }
    ],
    "code": "SBP-LIN-04-007",
    "created_at": "2020-07-02T11:44:04.000+02:00",
    "description": "The /etc/hosts.deny file contains network information that is used by many system applications and therefore must be readable for these applications to operate.",
    "equation": "1",
    "id": 4936,
    "last_modified_at": "2020-07-02T11:44:04.000+02:00",
    "level": "minimal",
    "name": "Ensure permissions on /etc/hosts.deny are configured",
    "os": [
        {
            "key": "ubuntu_1604_64"
        },
        {
            "key": "ubuntu_1804_64"
        },
        {
            "key": "ubuntu_2004_64"
        }
    ],
    "published_at": "2020-07-02T11:44:04.000+02:00",
    "rationale": "It is critical to ensure that the /etc/hosts.deny file is protected from unauthorized write access. Although it is protected by default, the file permissions could be changed either inadvertently or through malicious actions.",
    "reference": null,
    "remediation": "Run the following commands to set permissions on /etc/hosts.deny :\n\n<pre># chown root:root /etc/hosts.deny# chmod 644 /etc/hosts.deny</pre>",
    "require_sudo": true,
    "repositories": [
        {
            "name": "Security_Best_Practices"
        }
    ],
    "servers": [
        {
            "hostname": "heracles",
            "id": 1,
            "last_verification": "2020-09-13T22:26:14.000+02:00",
            "status": "gen_idle"
        }
    ],
    "type": null,
    "updated_at": "2020-09-11T15:38:52.000+02:00"
}

Point d'entrée permettant de relancer la règle de conformité sur tous les actifs associés.

Requête HTTP

PUT /api/v3/compliance/rules/<id>/recheck_servers

Permissions

Une clé d'API avec un niveau d'accès Complet est nécessaire.

Paramètres de requête

Paramètres Description
id
Obligatoire
ID de la règle de conformité à relancer.

Administration/Réglages

Groupes

Récupération de tous les Groupes

# Voir la section Authentification pour la définition des variables API_KEY, SECRET_KEY et API_URL

>>> CBWApi(API_URL, API_KEY, SECRET_KEY).groups()
# Voir la section Authentification pour la définition de la variable $client

PS> $client.groups()

Retourne un objet contenant les champs suivants :

[
    {
        "id": 13,
        "name": "non_admin",
        "description": null,
        "color": "#12AFCB"
    },
    {
        "id": 14,
        "name": "admin",
        "description": null,
        "color": "#12AFCB"
    }
]

Point d'entrée récupérant tous les groupes.

Requête HTTP

GET /api/v3/assets/groups

Permissions

Une clé d'API avec un niveau d'accès Lecture Seule est nécessaire.

Paramètres JSON

Paramètres Description
Pagination
Optionnel
Ce point d'entrée peut être paginé.

Récupération d'un Groupe

# Voir la section Authentification pour la définition des variables API_KEY, SECRET_KEY et API_URL

>>> CBWApi(API_URL, API_KEY, SECRET_KEY).group("14")
# Voir la section Authentification pour la définition de la variable $client

PS> $client.group("14")

Retourne un objet contenant les champs suivants :

{
    "id": 14,
    "name": "admin",
    "description": null,
    "color": "#12AFCB"
}

Point d'entrée récupérant un groupe donné.

Requête HTTP

GET /api/v3/assets/groups/<id>

Permissions

Une clé d'API avec un niveau d'accès Lecture Seule est nécessaire.

Paramètres de requête

Paramètres Description
id
Obligatoire
ID du groupe à récupérer.

Création d'un nouveau Groupe

# Voir la section Authentification pour la définition des variables API_KEY, SECRET_KEY et API_URL

PARAMETERS = {"name": "new_group", "description": "my description", "color": "#12AFCB"}

>>> CBWApi(API_URL, API_KEY, SECRET_KEY).create_group(PARAMETERS)
# Voir la section Authentification pour la définition de la variable $client

PS> $Parameters = @{
    "name" = "new_group"
    "description" = "my group's description"
    "color" = "#12AFCB"
}

PS> $client.create_group($Parameters)

Retourne un objet contenant les champs suivants :

{
    "id": 38,
    "name": "new_group",
    "description": null,
    "color": "#12AFCB"
}

Point d'entrée permettant de créer un groupe selon les paramètres donnés.

Requête HTTP

POST /api/v3/assets/groups

Permissions

Une clé d'API avec un niveau d'accès Complet est nécessaire.

Paramètres JSON

Paramètres Description
name
Obligatoire
Nom du nouveau groupe.
description
Optionnel
Description du nouveau groupe.
color
Optionnel
Couleur du nouveau groupe. La couleur doit être sous forme hexadécimale comme #12AFCB.

Modification d'un groupe existant

# Voir la section Authentification pour la définition des variables API_KEY, SECRET_KEY et API_URL

PARAMETERS = {"name": "new_group", "description": None, "color": "#12AFCB"}
ID = "38"

>>> CBWApi(API_URL, API_KEY, SECRET_KEY).update_group(ID, PARAMETERS)
# Voir la section Authentification pour la définition de la variable $client

PS> $Parameters = @{
    "name" = "new_group"
    "description" = "updated description"
    "color" = "#12AFCB"
}
PS> $Id = 38

PS> $client.update_group($Id, $Parameters)

Retourne un objet contenant les champs suivants :

{
    "id": 38,
    "name": "fine_name",
    "description": "A new description",
    "color": "#AAFF54"
}

Point d'entrée permettant de modifier un groupe existant.

Requête HTTP

PUT /api/v3/assets/groups/<id>

Permissions

Une clé d'API avec un niveau d'accès Complet est nécessaire.

Paramètres de requête

Paramètres Description
id
Obligatoire
ID du groupe à modifier.

Paramètres JSON

Paramètres Description
name
Optionnel
Nom à affecter au groupe.
description
Optionnel
Description à affecter au groupe.
color
Optionnel
Couleur à affecter au groupe. La couleur doit être sous forme hexadécimale comme #12AFCB.

Suppression d'un groupe

# Voir la section Authentification pour la définition des variables API_KEY, SECRET_KEY et API_URL

>>> CBWApi(API_URL, API_KEY, SECRET_KEY).delete_group("14")
# Voir la section Authentification pour la définition de la variable $client

PS> $client.delete_group("14")

Retourne un objet contenant les champs suivants :

{
    "id": 38,
    "name": "fine_name",
    "description": "A new description",
    "color": "#AAFF54"
}

Point d'entrée permettant de supprimer un groupe.

Requête HTTP

DELETE /api/v3/assets/groups/<id>

Permissions

Une clé d'API avec un niveau d'accès Complet est nécessaire.

Paramètres de requête

Paramètres Description
id
Obligatoire
ID du groupe à supprimer.

Identifiants enregistrés

Lister tous les identifiants enregistrés

# Voir la section Authentification pour la définition des variables API_KEY, SECRET_KEY et API_URL

>>> CBWApi(API_URL, API_KEY, SECRET_KEY).stored_credentials()
# Voir la section Authentification pour la définition de la variable $client

PS> $client.stored_credentials()

Retourne un objet contenant les champs suivants :


[
    {
        "endpoint": null,
        "id": 95,
        "name": "Default SSH key",
        "type": "CbwRam::Credentials::Key",
        "user": "foo"
    }
]

Requête HTTP

GET /api/v3/assets/credentials

Permissions

Une clé d'API avec un niveau d'accès Lecture Seule est nécessaire.

Paramètres de requête

Paramètres Description
type
Optionnel
Filtrer les identifiants par type.
Pagination
Optionnel
Ce point d'entrée peut être paginé.

Récupérer un jeu d’identifiants enregistrés

# Voir la section Authentification pour la définition des variables API_KEY, SECRET_KEY et API_URL

>>> CBWApi(API_URL, API_KEY, SECRET_KEY).stored_credential("95")
# Voir la section Authentification pour la définition de la variable $client

PS> $client.stored_credential(95)

Retourne un objet contenant les champs suivants :

{
    "endpoint": null,
    "id": 95,
    "name": "Default SSH key",
    "type": "CbwRam::Credentials::Key",
    "user": "foo"
}

Requête HTTP

GET /api/v3/assets/credentials/<id>

Permissions

Une clé d'API avec un niveau d'accès Lecture Seule est nécessaire.

Paramètres de requête

Paramètres Description
id
Obligatoire
ID du jeu d’identifiants à récupérer.

Créer un jeu d’identifiants

# Voir la section Authentification pour la définition des variables API_KEY, SECRET_KEY et API_URL

PARAMS = {
    "type" : "CbwRam::Credentials::SshWithPassword",
    "name" : "My password",
    "user" : "bob",
    "password" : "supersensitivepassword"
}
>>> CBWApi(API_URL, API_KEY, SECRET_KEY).create_stored_credential(PARAMS)
# Voir la section Authentification pour la définition de la variable $client

$Parameters = @{
    "type" = "CbwRam::Credentials::SshWithPassword"
    "name" = "My password"
    "user" = "bob"
    "password" = "supersensitivepassword"
}
PS> $client.create_stored_credential($Parameters)

Retourne un objet contenant les champs suivants :

{
    "endpoint": null,
    "id": 105,
    "name": "My password",
    "type": "CbwRam::Credentials::SshWithPassword",
    "user": "bob"
}

Requête HTTP

POST /api/v3/credentials

Permissions

Une clé d'API avec un niveau d'accès Complet est nécessaire.

Paramètres JSON

Paramètres Description
type
Obligatoire
Type de jeu d’identifiants à créer. Les types permis sont :
  • CbwRam::Credentials::SshWithPassword,
  • CbwRam::Credentials::Key,
  • CbwRam::Credentials::WinRmWithNegotiate,
  • CbwRam::Credentials::WinRmWithSsl,
  • CbwRam::Credentials::WinRmWithPlaintextOverSsl,
  • CbwRam::Credentials::DockerEngine,
  • CbwRam::Credentials::DockerRegistry,
  • CbwRam::Credentials::Snmp,
  • CbwRam::Credentials::Conjur.
name
Obligatoire
Nom du jeu d’identifiants.
endpoint
Optionnel
Point d’entrée (URL) pour les identifiants de type registre Docker, moteur d’exécution Docker ou Conjur.
user
Optionnel
Nom ou identifiant d’utilisateur.
password
Optionnel
Mot de passe des identifiants de type mot de passe.
key
Optionnel
Clé secrète des identifiants de type clé.
ca_cert
Optionnel
Certificat de l’autorité de certification pour les identifiants TLS comme pour un moteur d’exécution Docker.
client_cert
Optionnel
Certificat client pour les identifiants TLS comme comme pour un moteur d’exécution Docker.
client_key
Optionnel
Clé privée client pour les identifiants TLS comme pour un moteur d’exécution Docker.
auth_password
Optionnel
Mot de passe d’authentification pour les identifiants SNMP.
priv_password
Optionnel
Mot de passe de chiffrement pour les identifiants SNMP.
conjur_account
Optionnel
Nom d'utilisateur du compte Conjur utilisé lors de l'authentification.
conjur_host_id
Optionnel
ID de l'hôte Conjur (sous la forme host/myPolicy/myHost).
api_key
Optionnel
Clé d'API utilisée pour les identifiants de type Conjur.
bypass_proxy
Optionnel
Booléen permettant d'outrepasser un proxy.
insecure
Optionnel
Booléen permettant la désactivation de la vérification de certificat, pour les identifiants de type Conjur, Wallix, Vault HashiCorp, Docker registry, LDAP/AD, OpenStack, VMware et Kubernetes.

Modification d’un jeu d’identifiants

# Voir la section Authentification pour la définition des variables API_KEY, SECRET_KEY et API_URL

PARAMS = {
    "name" : "alice"
}
ID = "96"
>>> CBWApi(API_URL, API_KEY, SECRET_KEY).update_stored_credential(ID, PARAMETERS)
# Voir la section Authentification pour la définition de la variable $client

$Parameters = @{
    "name" = "alice"
}
$Id = 96
PS> $client.update_stored_credential($Id, $Parameters)

Retourne un objet contenant les champs suivants :

{
    "endpoint": null,
    "id": 95,
    "name": "Default SSH key",
    "type": "CbwRam::Credentials::Key",
    "user": "alice"
}

Requête HTTP

PATCH /api/v3/assets/credentials/<id>

Permissions

Une clé d'API avec un niveau d'accès Complet est nécessaire.

Paramètres de requête

Paramètres Description
id
Obligatoire
ID du jeu d’identifiants à modifier.

Paramètres JSON

Paramètres Description
name
Optionnel
Nom du jeu d’identifiants.
endpoint
Optionnel
Point d’entrée (URL) pour les identifiants de type registre Docker, moteur d’exécution Docker ou Conjur.
user
Optionnel
Nom ou identifiant d’utilisateur.
password
Optionnel
Mot de passe des identifiants de type mot de passe.
key
Optionnel
Clé secrète des identifiants de type clé.
ca_cert
Optionnel
Certificat de l’autorité de certification pour les identifiants TLS comme pour un moteur d’exécution Docker.
client_cert
Optionnel
Certificat client pour les identifiants TLS comme comme pour un moteur d’exécution Docker.
client_key
Optionnel
Clé privée client pour les identifiants TLS comme pour un moteur d’exécution Docker.
auth_password
Optionnel
Mot de passe d’authentification pour les identifiants SNMP.
priv_password
Optionnel
Mot de passe de chiffrement pour les identifiants SNMP.
conjur_account
Optionnel
Nom d'utilisateur du compte Conjur utilisé lors de l'authentification.
conjur_host_id
Optionnel
ID de l'hôte Conjur (sous la forme host/myPolicy/myHost).
api_key
Optionnel
Clé d'API utilisée pour les identifiants de type Conjur.
bypass_proxy
Optionnel
Booléen permettant d'outrepasser un proxy.
insecure
Optionnel
Booléen permettant la désactivation de la vérification de certificat, pour les identifiants de type Conjur, Wallix, Vault HashiCorp, Docker registry, LDAP/AD, OpenStack, VMware et Kubernetes.

Suppression d’un jeu d’identifiants

# Voir la section Authentification pour la définition des variables API_KEY, SECRET_KEY et API_URL

>>> CBWApi(API_URL, API_KEY, SECRET_KEY).delete_stored_credential("105")
# Voir la section Authentification pour la définition de la variable $client

PS> $client.delete_stored_credential(105)

Retourne un objet contenant les champs suivants :

{
    "endpoint": null,
    "id": 105,
    "name": "My password",
    "type": "CbwRam::Credentials::SshWithPassword",
    "user": "bob"
}

Requête HTTP

DELETE /api/v3/assets/credentials/<id>

Paramètres de requête

Paramètres Description
id
Obligatoire
ID du jeu d’identifiants à supprimer.

Nœuds

Récupération de tous les nœuds

# Voir la section Authentification pour la définition des variables API_KEY, SECRET_KEY et API_URL

>>> CBWApi(API_URL, API_KEY, SECRET_KEY).nodes()
# Voir la section Authentification pour la définition de la variable $client

PS> $client.nodes()

Retourne un objet contenant les champs suivants :

[
    {
        "id": 3,
        "name": "tech",
        "created_at": "2019-12-05T17:30:37.000+01:00",
        "updated_at": "2019-12-05T17:30:37.000+01:00"
    },
    {
        "id": 4,
        "name": "adm",
        "created_at": "2019-12-05T17:31:02.000+01:00",
        "updated_at": "2019-12-05T17:49:13.000+01:00"
    },
    {
        "id": 5,
        "name": "master",
        "created_at": "2019-12-05T17:31:12.000+01:00",
        "updated_at": "2019-12-06T14:57:18.000+01:00"
    }
]

Point d'entrée permettant de récupérer tous les nœuds.

Requête HTTP

GET /api/v3/nodes

Permissions

Une clé d'API avec un niveau d'accès Lecture Seule est nécessaire.

Paramètres JSON

Paramètres Description
Pagination
Optionnel
Ce point d'entrée peut être paginé.

Récupération d'un nœud

# Voir la section Authentification pour la définition des variables API_KEY, SECRET_KEY et API_URL

>>> CBWApi(API_URL, API_KEY, SECRET_KEY).node("4")

# Voir la section Authentification pour la définition de la variable $client

PS> $client.node("4")

Retourne un objet contenant les champs suivants :

{
    "id": 4,
    "name": "adm",
    "created_at": "2019-12-05T17:31:02.000+01:00",
    "updated_at": "2019-12-05T17:49:13.000+01:00"
}

Point d'entrée permettant de récupérer un nœud existant.

Requête HTTP

GET /api/v3/nodes/<id>

Permissions

Une clé d'API avec un niveau d'accès Lecture Seule est nécessaire.

Paramètres de requête

Paramètres Description
id
Obligatoire
ID du nœud à récupérer.

Suppression d'un nœud

# Voir la section Authentification pour la définition des variables API_KEY, SECRET_KEY et API_URL

PARAMS = {
    "new_id" : "3"
}
>>> CBWApi(API_URL, API_KEY, SECRET_KEY).delete_node("1", PARAMS)
# Voir la section Authentification pour la définition de la variable $client

$Parameters = @{
    "new_id" = "3"
}

PS> $client.delete_node("1", $Parameters)

Retourne un objet contenant les champs suivants :

{
    "id": 3,
    "name": "tech",
    "created_at": "2019-12-05T17:30:37.000+01:00",
    "updated_at": "2019-12-05T17:30:37.000+01:00"
}

Point d'entrée permettant de supprimer un nœud. L'ID d'un nouveau nœud est nécessaire afin de transférer les données sur le nouveau nœud.

Requête HTTP

DELETE /api/v3/nodes/<id>

Permissions

Une clé d'API avec un niveau d'accès Complet est nécessaire.

Paramètres de requête

Paramètres Description
id
Obligatoire
ID du nœud à supprimer.

Paramètres JSON

Paramètres Description
new_id
Obligatoire
ID du nœud sur lequel transférer les données.

Utilisateurs

Récupération de tous les Utilisateurs

# Voir la section Authentification pour la définition des variables API_KEY, SECRET_KEY et API_URL

>>> CBWApi(API_URL, API_KEY, SECRET_KEY).users()
# Voir la section Authentification pour la définition de la variable $client

PS> $client.users()

Retourne un objet contenant les champs suivants :

[
    {
        "id": 1,
        "login": "admin",
        "email": "admin@cyberwatch.fr",
        "name": "",
        "firstname": "",
        "locale": "en",
        "auth_provider": "local_password",
        "description": "",
        "role": "admin",
        "kibana_ability": true,
        "scope_global": true,
        "groups": []
    },
    {
        "id": 8,
        "login": "user",
        "email": "user@user.com",
        "name": "user",
        "firstname": "user",
        "locale": "en",
        "auth_provider": "local_password",
        "description": "",
        "role": "auditor",
        "kibana_ability": false,
        "scope_global": false,
        "groups": [
            {
                "id": 13,
                "name": "non_admin",
                "description": "my description",
                "color": "#12AFCB"
            },
            ...
            {
                "id": 14,
                "name": "admin",
                "description": "my description",
                "color": "#12AFCB"
            }
        ]
    }
]

Point d'entrée récupérant tous les utilisateurs.

Requête HTTP

GET /api/v3/users

Permissions

Une clé d'API avec un niveau d'accès Lecture Seule est nécessaire.

Paramètres JSON

Paramètres Description
auth_provider
Optionnel
Filtre les utilisateurs par auth_provider.
Valeurs possibles :
  • local_password
  • ldap
Pagination
Optionnel
Ce point d'entrée peut être paginé.

Récupération d'un Utilisateur

# Voir la section Authentification pour la définition des variables API_KEY, SECRET_KEY et API_URL

>>> CBWApi(API_URL, API_KEY, SECRET_KEY).user("10")
# Voir la section Authentification pour la définition de la variable $client

PS> $client.user("10")

Retourne un objet contenant les champs suivants :

{
    "id": 10,
    "login": "ldap_user",
    "email": "ldap@email.com",
    "name": "ldap_user",
    "firstname": "LDAP User",
    "locale": "en",
    "auth_provider": "ldap",
    "description": "",
    "role": "admin",
    "kibana_ability": true,
    "scope_global": true,
    "groups": []
}

Point d'entrée récupérant un utilisateur donné.

Requête HTTP

GET /api/v3/users/<id>

Permissions

Une clé d'API avec un niveau d'accès Lecture Seule est nécessaire.

Paramètres de requête

Paramètres Description
id
Obligatoire
ID de l'utilisateur à récupérer.

Erreurs

L'API utilise les codes d'erreurs suivants :

Paramètres Description
400 Bad Request -- La requête est invalide.
401 Unauthorized -- Mauvaise clé d'API, la signature est mal formée/mauvaise ou le client a une différence de date supérieure à 2 heures comparée à l'instance Cyberwatch.
403 Forbidden -- La requête n'est pas autorisée pour l'utilisateur actuel.
404 Not Found -- L'objet n'a pas été trouvé.
405 Method Not Allowed -- La méthode HTTP n'est pas autorisée pour cette requête.
500 Internal Server Error -- Votre instance Cyberwatch a rencontré une erreur inattendue. Veuillez réessayer plus tard.
502 Bad Gateway -- Votre instance Cyberwatch a rencontré un timeout pour cette requête.

Cyberwatch Air-gap

Utiliser Cyberwatch Air-gap avec l'API

Pour faciliter l'utilisation de Cyberwatch Air-gap avec l'API, nous fournissons un CLI pour Python et des scripts pour PowerShell

Avec Python

La manière recommandée d'utiliser Cyberwatch Air-gap avec Python est de passer par le CLI :

  1. Installer la librairie Python pour l'API avec la commande :
    pip3 install cbw-api-toolbox
  2. Télécharger les scripts pour Cyberwatch Air-gap en exécutant avec vos propres clés/URL la commande:
    cyberwatch-cli --api-url https://myinstance.local --api-key '...' --secret-key '...' airgap download-scripts
  3. Après avoir exécuté la commande, deux dossiers sont créés dans ./cyberwatch-airgap :
    - Le dossier scripts contient les scripts de Cyberwatch Air-gap pour générer des résultats.
    - Le dossier uploads qui sera utilisé pour Air-gap les résultats des scripts dans Cyberwatch.
  4. Exécuter les scripts sur le système à analyser et déplacer les résultats vers uploads :
    - Exemple pour un actif Linux
    ./cyberwatch-airgap/scripts/Linux/run > '$(hostname)'

    Note :Cela créera un fichier avec le résultat nommé avec le nom d'hôte que vous devez placer dans le dossier uploads.

  5. Envoyer les résultats des scripts présents dans ./cyberwatch-airgap/uploads à Cyberwatch avec :
    cyberwatch-cli --api-url https://myinstance.local --api-key '...' --secret-key '...' airgap upload
/

Avec PowerShell

La méthode recommandée pour envoyer des résultats de Cyberwatch Air-gap via l'API en Powershell :

  1. Cloner le dépôt de l'API PowerShell et configurer vos clés d'API.
  2. Télécharger les scripts de Cyberwatch Air-gap en exécutant à la racine du référentiel :
    ./examples/fetch_scripts_Air-gap.ps1
  3. Après avoir exécuté le script, deux dossiers sont créés dans ./cyberwatch-airgap :
    - Le dossier scripts contient les scripts de Cyberwatch Air-gap pour générer des résultats.
    - Le dossier uploads qui sera utilisé pour Air-gap les résultats des scripts dans Cyberwatch.
  4. Exécuter les scripts sur le système à analyser et déplacer les résultats vers Uploads
    - Exemple pour un actif Windows
    ./examples/Scripts/Windows/run.ps1 > ./${env:COMPUTERNAME}

    Note :Cela créera un fichier avec le résultat nommé avec le nom d'hôte que vous devez placer dans le dossier Uploads.

  5. Envoyer les résultats présents dans Uploads à Cyberwatch avec :
    ./examples/send_results_Air-gap.ps1
/

Lister tous les scripts de Cyberwatch Air-gap

# Voir la section Authentification pour la définition des variables API_KEY, SECRET_KEY et API_URL

>>> CBWApi(API_URL, API_KEY, SECRET_KEY).fetch_airgapped_scripts()
# Voir la section Authentification pour la définition de la variable $client

PS> $client.fetch_airgapped_scripts()

Retourne un objet contenant les champs suivants :

[
    {
        "id": 0,
        "type": "Scripts::Linux::InfoScript"
    },
    {
        "id": 1,
        "type": "Scripts::Windows::InfoScript"
    },
    {
        "id": 2,
        "type": "Scripts::Windows::PackagesScript"
    },
    {
        "id": 3,
        "type": "Scripts::Windows::WsusInfoScript"
    },
    {
        "id": 4,
        "type": "Scripts::Windows::WuaScript"
    },
    {
        "id": 5,
        "type": "Scripts::Macos::InfoScript"
    },
    {
        "id": 6,
        "type": "Scripts::Linux::InfoScript"
    },
    {
        "id": 7,
        "type": "Scripts::Aix::InfoScript"
    },
    {
        "id": 8,
        "type": "Scripts::Vmware::InfoScript"
    },
    {
        "id": 9,
        "type": "Scripts::NetworkDevice::Snmp::InfoScript"
    },
    {
        "id": 10,
        "type": "Scripts::Linux::PortsScript"
    },
    {
        "id": 11,
        "type": "Scripts::Windows::PortsScript"
    },
    {
        "id": 12,
        "type": "Scripts::Applicative::PortsScript"
    }
]

Point d'entrée permettant de lister tous les scripts de Cyberwatch Air-gap.

Requête HTTP

GET /api/v2/cbw_scans/scripts

Permissions

Une clé d'API avec un niveau d'accès Lecture Seule est nécessaire.

Récupérer un script spécifique de Cyberwatch Air-gap avec les détails

# Voir la section Authentification pour la définition des variables API_KEY, SECRET_KEY et API_URL

>>> CBWApi(API_URL, API_KEY, SECRET_KEY).fetch_airgapped_scripts("2")
# Voir la section Authentification pour la définition de la variable $client

PS> $client.fetch_importer_scripts(2)

Retourne un objet contenant les champs suivants :

{
    "attachment": "https://<cyberwatch_adress>/third_parties/wsusscan/027b51b364e8f50c54d4cd4f5755d81307b46c600c92fa210a092f207ec1fc08.cab",
    "contents": "function Get-PSScriptRoot\n{\n    $ScriptRoot = \"\"\n    Try\n    {\n        ...",
    "id": 4,
    "type": "Scripts::Windows::WuaScript",
    "version": "0"
}

Point d'entrée permettant de récupérer un script Cyberwatch Air-gap avec les détails.

Requête HTTP

GET /api/v2/cbw_scans/scripts

Permissions

Une clé d'API avec un niveau d'accès Complet est nécessaire.

Envoyer un résultat de script Cyberwatch Air-gap

# Voir la section Authentification pour la définition des variables API_KEY, SECRET_KEY et API_URL
with open(file_path, 'r') as filehandle:
    filecontent = filehandle.read()
    content = {"output": filecontent}
    print("INFO: Sending {} content to the API...".format(file))
    client.upload_airgapped_results(content)

>>> CBWApi(API_URL, API_KEY, SECRET_KEY).upload_airgapped_results("2")
# Voir la section Authentification pour la définition de la variable $client
PS> $client.upload_airgapped_results(2)

Retourne un objet contenant les champs suivants :

{

}

Point d'entrée permettant d'envoyer un résultat de script Cyberwatch Air-gap.

Requête HTTP

POST /api/v2/cbw_scans/scripts

Permissions

Une clé d'API avec un niveau d'accès Complet est nécessaire.

Cyberwatch Compliance Air-gap

Utiliser Cyberwatch Compliance Air-gap avec l'API

Pour faciliter l'utilisation de Cyberwatch Compliance Air-gap avec l'API, nous fournissons un CLI pour Python

Avec le CLI Python

La manière recommandée d'utiliser Cyberwatch Compliance Air-gap avec Python est de passer par le CLI :

  1. Installer la librairie Python pour l'API avec la commande :
    pip3 install cbw-api-toolbox
  2. Télécharger les scripts pour Cyberwatch Compliance Air-gap en exécutant avec vos propres clés/URL la commande :
    cyberwatch-cli --api-url https://myinstance.local --api-key '...' --secret-key '...' airgap download-compliance-scripts --os ... --repositories ...
  3. - Paramètre 'os' : mettre une des clés du système d'exploitation qui se trouve ici
    - Paramètre 'repositories' : mettre les référentiels que vous souhaitez récupérer (exemple : --repositories CIS_Benchmark, Security_Best_Practices).
  4. Après avoir exécuté la commande, deux dossiers sont créés dans cyberwatch-airgap-compliance :
    - Le dossier scripts contient les scripts de Cyberwatch Compliance Air-gap pour générer des résultats.
    - Le dossier uploads qui sera utilisé pour importer les résultats des scripts dans Cyberwatch.
  5. Pour exécuter les scripts, vous devez déplacer le dossier scripts lui-même vers l'actif que vous souhaitez analyser et exécuter le script run. Pour éviter tout risque d'exécution d'un script indésirable, prenez le dossier lui-même, et pas seulement son contenu.
    bash ./scripts/run
    PowerShell: ./scripts/run.ps1

    Note : Cela créera un dossier uploads avec les résultats. Déplacer ensuite les résultats vers le dossier cyberwatch-compliance-airgap/uploads sur le système avec le CLI.

  6. Envoyer les résultats des scripts présents dans ./cyberwatch-airgap-compliance/uploads à Cyberwatch avec :
    cyberwatch-cli --api-url https://myinstance.local --api-key '...' --secret-key '...' airgap upload-compliance
/

Lister tous les scripts de Cyberwatch Compliance Air-gap

# Voir la section Authentification pour la définition des variables API_KEY, SECRET_KEY et API_URL

>>> CBWApi(API_URL, API_KEY, SECRET_KEY).fetch_compliance_airgapped_scripts({"os": "ubuntu_2004_64", "repositories": ["CIS_Benchmark"]})
# Voir la section Authentification pour la définition de la variable $client

Retourne un objet contenant les champs suivants :

[
"filename": "CIS-linux-6.2.17_1.sh",
"script_content": "echo 'IDENTIFIER_RULE:CIS-linux-6.2.17'
                   echo 'IDENTIFIER_CHECK_ORDER:1'
                   echo 'IDENTIFIER_HOSTNAME:$(hostname)'
                   # Check if the next command has correct return
                   cut -f3 -d':' /etc/group | sort -n | uniq -c | while read -r x ; do
                  [ -z '${x}' ] && break
                  set - $x
                  if [ $1 -gt 1 ]; then
                        groups=$(awk -F: \'($3 == n) { print $1 }\' n=$2 /etc/group | xargs)
                        echo 'Duplicate GID ($2): ${groups}'
                      fi
                  done
                  "
...
]

Point d'entrée permettant de lister tous les scripts de Cyberwatch Compliance Air-gap spécifique à un os/groupe.

Requête HTTP

GET /api/v2/compliances/scripts

Permissions

Une clé d'API avec un niveau d'accès Complet est nécessaire.

Envoyer un résultat de script Cyberwatch Compliance Air-gap

# Voir la section Authentification pour la définition des variables API_KEY, SECRET_KEY et API_URL
>>> with open(file_path, 'r') as filehandle:
      filecontent = filehandle.read()
      content = {"output": filecontent}
      print("INFO: Sending {} content to the API...".format(filehandle))
      CBWApi(API_URL, API_KEY, SECRET_KEY).upload_compliance_airgapped_results(content)
# Voir la section Authentification pour la définition de la variable $client

Retourne un objet contenant les champs suivants :

{

}

Point d'entrée permettant d'envoyer un résultat de script Cyberwatch Compliance Air-gap.

Requête HTTP

POST /api/v2/cbw_scans/scripts

Permissions

Une clé d'API avec un niveau d'accès Complet est nécessaire.