Guide utilisateur de l'API

Modifié le Jeu, 18 Avr. à 4:25 H


Grâce à cet article, vous saurez utiliser l'API du Portail.

SOMMAIRE

Limitations
Authentification
Plan d'action
Récupérer des bulletins Yuno
Récupérer des composants techniques (assets)
- Filtres de recherche
- Liste des propriétés disponibles

Limitations

En cas d'un nombre important de résultats, l'API remonte au maximum 50 résultats par page. Vous devez utiliser le système de pagination pour accéder aux autres résultats.
à l'heure actuelle, notre APi est en mode pull uniquement.

Authentification

Authentification par clé d'API (recommandé)

Avis aux managers : La clé d'API est personnelle ! Pour des raisons de sécurité, vous ne pouvez pas la générer pour un autre utilisateur.

Etape 1 : Générer une clé d'API

Une clé d'API (aussi appelée token) est un identifiant alternatif au couple login/mot de passe.

Elle doit être générée dans les paramètres utilisateur :

Pour accéder à ces paramètres, aller en haut à droite de l'interface du Portail et cliquer sur vos initiales puis sur Paramètres du compte.
Cliquer sur l'onglet Sécurité.

Les requêtes utilisant la clé d'API s'exécuteront dans le contexte de l'utilisateur, donc avec des accès identiques.

Etape 2 : lnclure la clé dans l'entête

La clé d'API doit être incluse dans l'en-tête `Authorization` (avec le type `Bearer`) :

Authorization: Bearer $API_key

La requête devra avoir la forme suivante, en incluant l'entête Authorization :

GET https://leportail.xmco.fr/api/user/current HTTP/1.1
Host: leportail.xmco.com
Authorization: Bearer xxxxxxxxxxxxxxxxxxx

Voici un example de requête cUrl :

curl -H "Authorization: Bearer xxxxxxxxxxxxxxxxxxx" 'https://leportail.xmco.fr/api/user/current'

Lorsque l'authentification par clé d'API est utilisée, le second facteur n'est pas nécessaire (si activé).

Authentification classique

Pour s'authentifier, effectuer une requête HTTP POST vers https://leportail.xmco.fr/api/authenticate.

La requête devra avoir la structure suivante :

POST /api/authenticate HTTP/1.1
Host: leportail.xmco.fr
Content-Type: application/json
Content-Length: 76
Connection: close

{"username": "value", "password": "password"}

Voici un example de requête cUrl :

curl -i -d '{"username": "value", "password": "password"}' -H "Content-Type: application/json" -X POST 'https://leportail.xmco.fr/api/authenticate'

La réponse à cette requête comportera un cookie de session, identifié sous le nom XMSESSION.

Il devra être transmis à chaque requête vers l'API.
Pour cela, les requêtes devront inclure un header Cookie de la forme XMSESSION=xxxxx.

Si l'authentification à 2 facteurs est activée, une requête supplémentaire vers https://leportail.xmco.fr/api/validate_otp est nécessaire.

Le cookie de session récupéré à partir de la requête vers https://leportail.xmco.fr/api/authenticate devra être inclus à cette requête, qui aura la structure suivante :

POST /api/validate_otp HTTP/1.1
Host: leportail.xmco.fr
Content-Type: application/json
Content-Length: 76
Connection: close
Cookie: XMSESSION=xxxxxxxxxx

{"otp": "le code reçu par SMS"}

Voici un exemple de requête cUrl :

curl -i -d '{"otp": "the code received by SMS"}' -H "Content-Type: application/json" -H "Cookie: XMSESSION=xxxxxxxxxx" -X POST 'https://leportail.xmco.fr/api/validate_otp'

La réponse à cette requête comportera le cookie de session qui devra être transmis à chaque requête vers l'API.
Le cookie de session récupéré à partir de la requête vers https://leportail.xmco.fr/api/authenticate ne sera plus utilisé.

Pour toutes vos prochaines requêtes, il va falloir inclure l'entête Cookie sous la forme XMSession=xxxxx.

Si vous utilisez l'authentification basique, utilisez le cookie de session récupéré à l'étape 1;
Si vous utilisez l'authentification multi-facteur, utilisez le cookie de session récupéré à l'étape 2.

Plan d'action

Accéder à la liste des tickets m'étant assignée

Etape 1 : Obtenir son identifiant utilisateurs (user_id)

Cet identifiant permettra d'effectuer des filtres sur les tickets qui vous sont assignés. Il est contenu dans le champ user._id obtenu par une requête GET à l'url https://leportail.xmco.fr/api/user/current.

Voici un example de requête cUrl :

curl -H "Content-Type: application/json" -H "Cookie: XMSESSION=xxxxxxxxxx" 'https://leportail.xmco.fr/api/user/current'

La réponse aura la structure suivante :

{
"user": {
"_id": "55ca2585f2c3425976c28abf",
"first_name": "Jean-Yves",
"company": "xxxxxxxxxx",
"...": "..."
},
"...": "..."
}

Cet identifiant peut être récupéré via la rubrique Mon Compte directement sur le Portail. Il est directement dans l'URL (https://leportail.xmco.fr/users/edit/user_id)

Etape 2 : Obtenir la liste des tickets m'étant assignés

Cette liste peut s'obtenir via une requête GET à https://leportail.xmco.fr/api/action_plan/list et en spécifiant l'argument assignee_id avec l'identifiant obtenu précédemment.

Voici un example de requête cUrl :

curl -G -g -H "Content-Type: application/json" -H "Cookie: XMSESSION=xxxxxxxxxx" 'https://leportail.xmco.fr/api/action_plan/list' --data-urlencode 'assignee_id=55ca2585f2c3425976c28abf'

La réponse aura le format suivant :

{
"_items": [
  {
  "_id": "5d3bfe1ad234ff01d3a35e2c",
  "_created": "Mon, 06 May 2019 15:52:14 GMT",
  "_deleted": false,
  "_etag": "e8b7960beb33e23c7e771f91e4dd68142f852f9a",
  "_latest_version": 2,
  "_updated": "Thu, 01 Aug 2019 13:29:40 GMT",
  "_version": 3,
  "assignee": "...",
  "certified": false,
  "company": "...",
  "custom_fields": {
     "category": "disclosure",
     "subcategory": "disclosure_other",
     "identification": "automatic",
     "scope": "passive"
  },
"description": "...",
"description_format": "html",
"impact": 0.0,
"is_open": false,
"journals": [
  "..."
],
"owner": "55ca2585f2c3425976c28ac0",
"quickwin": false,
"ref_id": 331750,
"revision": 0,
"scope": "5d3bfe0cd234ff01d3a35d9a",
"severity": "low",
"status": "new",
"title": "Une adresse IP est référencée dans la liste noire Spamhaus",
"tracker": "5ca6019ff44a43003f808ffd",
"type": "serenety_action_ticket",
"users": [
   "..."
 ],
"closed_on": "Thu, 01 Aug 2019 13:29:40 GMT",
"assets": [],
"cpe_names": []
}
],
"_meta": {
  "total": 1
}
}

Pour des explications détaillées sur les champs récupérées, vous pouvez vous référer aux informations suivantes :

_created : date de création
_updated : date de la dernière modification
assignee : identifiant de l'utilisateur assigné au ticket
company : identifiant de la société
custom fields : liste de champs personnalisés. Pour les alertes Serenety, il y aura les lignes suivantes :
- category
- subcategory
- identification (manuelle ou automatique)
- scope (passive ou active)
description : description du ticket
description_format : format de la description (html ou texte brut)
impact : utile pour les audits, mesure l'impact d'un ticket sur la note d'un audit
is_open : si le ticket est ouvert (vrai/faux)
closed_on : date à laquelle le ticket a été fermé (nécessite donc que is_open = faux)
severity (faible, moyen, elevée)
status (nouveau, en cours, en attente, résolu)
title
tracker
type

Accéder à la liste des tickets de la société

Etape 1 : Obtenir son identifiant de la société (company_id)

Cet identifiant est contenu dans le champ user.company obtenu par une requête GET à

https://leportail.xmco.fr/api/user/current.

Voici un example de requête cUrl :

curl -H "Content-Type: application/json" -H "Cookie: XMSESSION=xxxxxxxxxx" 'https://leportail.xmco.fr/api/user/current'

La réponse aura le format suivant :

{
  "user": {
    "_id": "55ca2585f2c3425976c28abf",
    "first_name": "Jean-Yves",
    "company": "xxxxxxxxxx",
    "...": "..."
  },
  "...": "..."
}

Etape 2 : Obtenir la liste des tickets de la société

Cette liste peut s'obtenir via une requête GET à https://leportail.xmco.fr/api/action_plan/list et en spécifiant l'argument company_id avec l'identifiant obtenu précédemment.

Les résultats renvoyés sont limités selon vos droits d'accès ! Aucun filtre n'étant appliqué, le résultat peut donc être volumineux.

Voici un example de requête cUrl :

curl -g -XPOST -H "Content-Type: application/json" -H "Cookie: XMSESSION=xxxxxxxxxx" 'https://leportail.xmco.fr/api/tracker/by_company' --data '{"company_id":"55ca2584f2c3425976c28aa4"}'

La réponse aura le format suivant :

{
"_items": [
  {
  "_id": "5d3bfe1ad234ff01d3a35e2c",
  "_created": "Mon, 06 May 2019 15:52:14 GMT",
  "_deleted": false,
  "_etag": "e8b7960beb33e23c7e771f91e4dd68142f852f9a",
  "_latest_version": 2,
  "_updated": "Thu, 01 Aug 2019 13:29:40 GMT",
  "_version": 3,
  "assignee": "...",
  "certified": false,
  "company": "...",
  "custom_fields": {
     "category": "disclosure",
     "subcategory": "disclosure_other",
     "identification": "automatic",
     "scope": "passive"
  },
"description": "...",
"description_format": "html",
"impact": 0.0,
"is_open": false,
"journals": [
  "..."
],
"owner": "55ca2585f2c3425976c28ac0",
"quickwin": false,
"ref_id": 331750,
"revision": 0,
"scope": "5d3bfe0cd234ff01d3a35d9a",
"severity": "low",
"status": "new",
"title": "Une adresse IP est référencée dans la liste noire Spamhaus",
"tracker": "5ca6019ff44a43003f808ffd",
"type": "serenety_action_ticket",
"users": [
   "..."
 ],
"closed_on": "Thu, 01 Aug 2019 13:29:40 GMT",
"assets": [],
"cpe_names": []
}
],
"_meta": {
  "total": 1
}
}

Accéder aux tickets liés à un module particulier (Audit, Yuno, Serenety)

Etape 1 : Obtenir son identifiant de société (company_id)

Voir la section précédente.

Etape 2 : Obtenir les identifiants des trackers

Cette liste pouvant évoluer au cours du temps, nous vous proposons de la récupérer de manière dynamique.

Cette liste peut s'obtenir via une requête POST vers l'URL https://leportail.xmco.fr/api/tracker/by_company en spécifiant l'argument company_id avec l'identifiant obtenu précédemment et avec l'une des valeurs suivantes pour le paramètre module: watch, serenety ou pentest.

Nous pouvons ainsi extraire la liste des identifiants des trackers, contenus dans le champ _id de chaque document de la liste renvoyée par l'API.

Le paramètre queryExtras supporte la synthaxe MongoDB.

Différents filtres sont disponibles, parmi lesquels :

les tickets ouverts : =vrai

"is_open":{"$eq":true}

le statut "Nouveau" ou "En cours" :

"status":{"$in":["new","in_progress"]}

les tickets créés après une date précise :

"_created":{"$gt":"2000-01-31T22:00:00.000Z"}

Voici un example de requête cUrl pour les alertes Serenety :

curl -g -XPOST -H "Content-Type: application/json" -H "Cookie: XMSESSION=xxxxxxxxxx"
'https://leportail.xmco.fr/api/tracker/by_company' --data '{"module":"serenety","company_id":"company_id"}'

La réponse aura le format suivant :

{
  "_items": [
  {
    "_id": "5ca6019ff44a43003f808ffd",
    "_created": "Thu, 04 Apr 2019 13:07:43 GMT",
    "_updated": "Thu, 04 Apr 2019 13:07:43 GMT",
    "_deleted": false,
    "_etag": "16e0ecc7-3b47-4dc1-b2ed-4324d3d9ca57",
    "_version": 1,
    "_latest_version": 1,
    "name": {
      "fr": "Alertes Serenety",
      "en": "Serenety alerts"
    },
    "module": "serenety",
    "fields": [
      "..."
    ]
  },
  "..."
  ]
}

Etape 3 : Récupérer la liste des tickets associés au produit

Cette liste peut s'obtenir via une requête GET à https://leportail.xmco.fr/api/action_plan/list et en spécifiant l'argument company_id avec l'identifiant obtenu précédemment et en paramétrant l'argument queryExtras avec le filtre voulu. Dans notre cas précis, nous utiliserons la syntaxe suivante :

'tracker':{'$in': ['liste des identifiants de trackers récupérés précédemment]}

Voici un example de requête cUrl :

curl -G -g -H "Content-Type: application/json" -H "Cookie: XMSESSION=xxxxxxxxxx" 'https://leportail.xmco.fr/api/action_plan/list' --
data-urlencode 'queryExtras={"tracker":{"$in":["5ca6019ff44a43003f808ffd","5ca6019ff44a43003f808ffe"]}}' --data-urlencode
'company_id=55ca2584f2c3425976c28aa4'

La réponse aura le format suivant :

{
  "_items": [
  {
    "_id": "5d3bfe1ad234ff01d3a35e2c",
    "_created": "Mon, 06 May 2019 15:52:14 GMT",
    "_deleted": false,
    "_etag": "e8b7960beb33e23c7e771f91e4dd68142f852f9a",
    "_latest_version": 2,
    "_updated": "Thu, 01 Aug 2019 13:29:40 GMT",
    "_version": 3,
    "assignee": "...",
    "certified": false,
    "company": "...",
    "custom_fields": {
      "category": "disclosure",
      "subcategory": "disclosure_other",
      "identification": "automatic",
      "scope": "passive"
    },
    "description": "...",
    "description_format": "html",
    "impact": 0.0,
    "is_open": false,
    "journals": [
      "..."
    ],
    "owner": "55ca2585f2c3425976c28ac0",
    "quickwin": false,
    "ref_id": 331750,
    "revision": 0,
    "scope": "5d3bfe0cd234ff01d3a35d9a",
    "severity": "low",
    "status": "new",
    "title": "Une adresse IP est référencée dans la liste noire Spamhaus",
    "tracker": "5ca6019ff44a43003f808ffd",
    "type": "serenety_action_ticket",
    "users": [],
    "closed_on": "Thu, 01 Aug 2019 13:29:40 GMT",
    "assets": [],
    "cpe_names": []
  }
  ],
  "_meta": {
     "total": 1
  }
}

Mettre à jour un ticket d'action

Etape 1 : Obtenir l'identifiant et l'etag du ticket à modifier

Cette information se trouve dans les champs _id et _etag, obtenus via les requêtes précédemment décrites.

Etape 2 : Mettre à jour le ticket

Une mise à jour consiste en une requête PATCH vers https://leportail.xmco.fr/api/action_plan/xxxxxxxxx.

Cette requête doit contenir `l'etag` dans son en-tête If-Match ainsi que les modifications sous la forme d'un dictionnaire.

Voici un exemple de requête cUrl :

curl -g -X PATCH -H "Content-Type: application/json" -H "Cookie: XMSESSION=xxxxxxxxxx" -H "If-Match: etag"
'https://leportail.xmco.fr/api/action_plan/xxxxxxxxx' --data '{"severity":"low","status":"in_progress"}'

La réponse aura le format suivant :

{
  "_created": "Tue, 06 Aug 2019 08:27:32 GMT",
  "_deleted": false,
  "_etag": "aad40814de0e81ca0420273d05b906a59c3b6976",
  "_id": "xxxxxxxxx",
  "_latest_version": 2,
  "_links": {
    "self": {
      "href": "action_plan/xxxxxxxxx",
      "title": "Actionticket"
    }
  },
  "_status": "OK",
  "_updated": "Thu, 08 Aug 2019 14:03:57 GMT",
  "_version": 2
}

Ajouter un commentaire sur une alerte ou un ticket d'action

Pour ajouter un commentaire, il faut utiliser une requête PATCH vers https://leportail.xmco.fr/api/action_plan/xxxxxxxxx.

Cette requête doit contenir `l'etag` dans son en-tête If-Match ainsi que les modifications sous la forme d'un dictionnaire.

Voici un exemple de requête cUrl :

curl -g -X PATCH -H "Content-Type: application/json" -H "Cookie: XMSESSION=xxxxxxxxx" -H "If-Match: $_etag" 'https://leportail.xmco.fr/api/action_plan/$_id' --data '{"journals":[{"notes”:”This is a comment"}]}'

Récupérer des fichiers d'une alerte ou un ticket d'action

Etape 1 : Obtenir l'identifiant de l'alerte ou du ticket d'action à modifier

Cette information se trouve dans les champs _id, obtenu via les requêtes précédemment décrites.

Etape 2 : Obtenir le ou les fichier(s) associé(s) au ticket

Voici un exemple de requête GET (où il faut remplacer {{id_actionticket}} par l'_id précédemment obtenu.) :

GET https://leportail.xmco.fr/api/file/?sort=-_created&page=1&max_results=25&where={"attached_to.$id":"{{id_actionticket}}", "attached_to.$ref":"actionticket"}

La réponse aura le format suivant :

{ "_items": [
  {
    "_id": "66017ec3659aa1001cb59f97", 
    "data": "(data)", 
    "name": "XMCO-blocklist.png", 
    "size": 277988, 
    "type": "image/png", 
    "owner": "$id_owner", 
    "attached_to": {
      "$id": "$id_actionticket", 
      "$ref": "actionticket"
     }, 
    "company": "$id_company", 
    "_updated": "Tue, 26 Mar 2024 16:41:09 GMT", 
    "_created": "Mon, 25 Mar 2024 13:40:19 GMT", 
    "_deleted": false, 
    "updatable": true, 
    "_etag": "46e773f3-0e28-466e-9624-b7c6d0589f75", 
   "_links": {
     "self": {
       "title": "File", 
       "href": "file/66017ec3659aa1001cb59f97"}
    }
}
],
"_links": {
  "parent": {
    "title": "home", 
    "href": "/"},
   "self": {
    "title": "file",
    "href": "file?where={\"attached_to.$id\":\"6602faa5659aa1001cb5a266\",\"attached_to.$ref\":\"actionticket\"}&sort=-_created"}
},
"_meta": {
  "page": 1, 
  "max_results": 25, 
  "total": 1}
}

Récupérer des bulletins Yuno

Format de données

Les bulletins YUNO peuvent être récupérés en effectuant une requête GET vers https://leportail.xmco.fr/api/advisory.

Voici un exemple de requête cUrl :

curl -H "Content-Type: application/json" -H "Cookie: XMSESSION=xxxxxxxxxx" 'https://leportail.xmco.fr/api/advisory'

L'appel renverra un document au format JSON, qui aura la structure suivante :

Pour un bulletin INFO :

{
  "_items": [
  {
    "_id": "5b893bf6503bc6000e93d13e",
    "exploitation_vector": "none",
    "platforms": [],
    "references": "https://www.bankinfosecurity.com/air-canada-attack-exposed-data-on-20000-mobile-app-users-a-11441",
    "nonvulnerable": "",
    "vulnerable": "",
    "content_fr": {
      "description": "La compagnie aérienne Air Canada a forcé ses 1,7 million d’utilisateurs à changer leur mot de passe après avoir
détecté une activité anormale. Air Canada a annoncé que 20 000 comptes auraient été exposés. Les comptes contiendraient des
détails sur les passeports des clients. La plupart des informations dépendent de ce que l’utilisateur souhaite partager. En règle
général, un profile d’application contient au moins le nom, le prénom, une adresse postale et un email. Mais d’autres utilisateurs
enregistrent également leur passeport en incluant : date de naissance, nationalité, date d’expiration du document, pays de
délivrance et pays de résidence. Air Canada ajoute que la faille n’a exposé aucun moyen de payement. La compagnie assure que
ces données sont chiffrées et en accord avec les règles du PCI-DSS.",
      "title": "Une cyber attaque a exposé les données de 20 000 utilisateurs mobiles d’Air Canada",
      "description_format": "text",
      "mitigation": "",
      "remediation": "",
      "expert_advice": ""
    },
   "advisory_type": "INFO",
   "severity": "high",
    "cve_refs": [],
    "exploit_code": "",
    "damage": [],
    "languages": ["fr"],
    "ref": "2018-3543",
    "files": [],
    "impact": 0,
    "vendor": "",
    "content_en": {
      "description": "",
      "title": "Air Canada: Attack Exposed 20,000 Mobile App Users’ Data",
      "description_format": "text",
      "mitigation": "",
      "remediation": "",
      "expert_advice": ""
    },
    "tags": [
      "Attaque",
      "Vie privée"
    ],
    "ioc": "",
    "official_title": "Air Canada: Attack Exposed 20,000 Mobile App Users’ Data",
    "exploit_code_lang": "none",
    "_created": "Fri, 31 Aug 2018 07:55:33 GMT",
    "_updated": "Fri, 31 Aug 2018 13:00:38 GMT",
    "_deleted": false,
    "_etag": "71ac4bf26b5aae02a6ab7bf9854cc7cbed344c3c",
    "cpe_names": [],
    "_links": {
      "parent": {
         "title": "home",
          "href": "/"
      },
    "self": {
      "title": "Advisory",
      "href": "advisory/5b893bf6503bc6000e93d13e"
    },
    "collection": {
      "title": "advisory",
      "href": "advisory"
    }
  },
  "_version": 1,
  "_latest_version": 1
},
{
  "_id": "abcdefabcdefabcdefabcdef",
  "...": "..."
}
],
"_links": {
"parent": {
"title": "home",
"href": "/"
},
"self": {
"title": "advisory",
"href": "advisory?max_results=25"
},
"next": {
"title": "next page",
"href": "advisory?max_results=25&page=2"
},
"last": {
"title": "last page",
"href": "advisory?max_results=25&page=36700"
}
},
"_meta": {
"page": 1,
"max_results": 25,
"total": 36700
}
}

Pour un bulletin PATCH :

{
  "_items": [
  {
    "_id": "5b893bc5503bc6000e93d0e0",
    "exploitation_vector": "remote",
    "platforms": ["55ca2585f2c3425976c28ac1"],
    "references": "https://www.synology.com/fr-fr/support/security/Synology_SA_18_51",
    "nonvulnerable": "",
    "vulnerable": "* DSM 6.2 * DSM 6.1 * DSM 5.2",
    "content_fr": {
      "description": "Une vulnérabilité a été corrigée au sein des produits de Synology. Son exploitation permettait à un attaquant de
voler des informations et de manipuler des données. La faille de sécurité non référencée provenait d’une erreur non spécifiée au
sein de Synology DiskStation Manager (DSM). En exploitant cette vulnérabilité un attaquant était en mesure de voler des
informations et d’injecter du code JavaScript et HTML dans les pages accédées par les clients.",
      "title": "Manipulation de données et vol d’informations via une vulnérabilité au sein des produits Synology (Synology-SA-18:51
DSM)",
      "description_format": "text",
      "mitigation": "",
      "remediation": "Le CERT-XMCO recommande l’installation de la version 6.2.1-23824 des produits DSM 6.2, DSM 6.1 et DSM 5.2.",
      "expert_advice": ""
    },
    "advisory_type": "PATCH",
    "severity": "medium",
    "cve_refs": [],
    "exploit_code": "",
    "damage": [
      "data_tampering",
      "data_theft"
    ],
    "languages": ["fr"],
    "ref": "2018-3540",
    "files": [],
    "impact": 0,
    "vendor": "SYNOLOGY",
    "content_en": {
      "description": "",
      "title": "Data manipulation and information disclosure via a vulnerability in Synology products (Synology-SA-18:51 DSM)",
      "description_format": "text",
      "mitigation": "",
      "remediation": "The CERT-XMCO recommends installing the version 6.2.1-23824 of the products DSM 6.2, DSM 6.1 and DSM 5.2.",
      "expert_advice": ""
    },
    "tags": [],
    "ioc": "",
    "official_title": "Synology-SA-18:51 DSM",
    "exploit_code_lang": "none",
    "_created": "Fri, 31 Aug 2018 07:08:39 GMT",
    "_updated": "Fri, 31 Aug 2018 12:59:49 GMT",
    "_deleted": false,
    "_etag": "2060ecb85285eea4774f35251df1b93fc0dbfd60",
    "cpe_names": ["59a3ccc5f2c3427b958db52d"],
    "_links": {
      "parent": {
        "title": "home",
        "href": "/"
      },
      "self": {
        "title": "Advisory",
        "href": "advisory/5b893bc5503bc6000e93d0e0"
      },
      "collection": {
        "title": "advisory",
        "href": "advisory"
      }
    },
    "_version": 1,
    "_latest_version": 1
  },
}
"_id": "abcdefabcdefabcdefabcdef",
"...": "..."
}
],
"_links": {
"parent": {
"title": "home",
"href": "/"
},
"self": {
"title": "advisory",
"href": "advisory?max_results=25"
},
"next": {
"title": "next page",
"href": "advisory?max_results=25&page=2"
},
"last": {
"title": "last page",
"href": "advisory?max_results=25&page=36700"
}
},
"_meta": {
  "page": 1,
  "max_results": 25,
  "total": 36700
}
}

Filtres de recherche

Il est possible d’appliquer des filtres de recherche grâce au paramètre where. Le format à appliquer est celui des requêtes MongoDB. La totalité des opérations MongoDB est supportée, à l'exception des opérateurs $regex et $where .

Les requêtes suivantes sont toutes des exemples de filtres :

Ne retourner que des bulletins de veille de type INFO

curl -g -H "Content-Type: application/json" -H "Cookie: XMSESSION=xxxxxxxxxx" 'https://leportail.xmco.fr/api/advisory' --data-urlencode 'where={"advisory_type":"INFO"}'

Ne retourner que les bulletins publiés entre le 8 et 22 février 2023 (les dates sont au format RFC2822)

curl -g -H "Content-Type: application/json" -H "Cookie: XMSESSION=xxxxxxxxxx" 'https://leportail.xmco.fr/api/advisory' --data-urlencode 'where={"_created":{"$gte":"Thu, 8 Feb 2023 00:00:00 GMT","$lte":"Thu, 22 Feb 2023 00:00:00 GMT"}}'

Ne retourner que les bulletins de criticité élevée

curl -g -H "Content-Type: application/json" -H "Cookie: XMSESSION=xxxxxxxxxx" 'https://leportail.xmco.fr/api/advisory' --data-urlencode 'where={"severity":"high"}'

Ne retourner que les bulletins concernant Debian

curl -g -H "Content-Type: application/json" -H "Cookie: XMSESSION=xxxxxxxxxx" 'https://leportail.xmco.fr/api/advisory' --data-urlencode 'where={"cpe_names":"55ca2587f2c3425976c28d8d"}'

Ne retourner que les bulletins concernant la technologie Wordpress, de criticité supérieure ou égale à Moyenne, publiés depuis le 8 février 2023

curl -g -H "Content-Type: application/json" -H "Cookie: XMSESSION=xxxxxxxxxx" 'https://leportail.xmco.fr/api/advisory' --data-urlencode 'where={"cpe_names":"55ca2586f2c3425976c28d43","severity":{"$in":["urgent","high","medium"]},"_created":{"$gte":"Thu, 8 Feb 2023 00:00:00 GMT"}}'

Récupérer l'identifiant d'une technologie

Comme illustré dans les exemples de requêtes, il est possible d'appliquer des filtres pour récupérer les bulletins concernant une technologie en particulier. Il est pour cela nécessaire de connaître l'identifiant de la technologie en question.

Il est possible de rechercher une technologie à partir de son nom en effectuant une requête GET vers l'endpoint cpename .

Par exemple, si vous désirez obtenir des informations sur la technologie Wordpress :

curl -H "Content-Type: application/json" -H "Cookie: XMSESSION=xxxxxxxxxx" 'https://leportail.xmco.fr/api/cpename' --data-urlencode 'where={"name":"Wordpress"}'

La réponse aura le format suivant :

{
  "_items": [
  {
    "_id": "55ca2586f2c3425976c28d43",
    "edition": "*",
    "uri_23": "cpe:/a:wordpress:wordpress",
    "meta_ref": null,
    "is_meta": true,
    "target_hw": "*",
    "is_custom": true,
    "sw_edition": "*",
    "version": "*",
    "product": "wordpress",
    "fs": "cpe:2.3:a:wordpress:wordpress:*:*:*:*:*:*:*:*",
    "vendor": "wordpress",
    "update": "*",
    "target_sw": "*",
    "language": "*",
    "part": "a",
    "name": "Wordpress",
    "cpe_names": [],
     "other": "*",
    "_created": "Tue, 11 Aug 2015 16:40:38 GMT",
    "_updated": "Tue, 11 Aug 2015 16:40:38 GMT",
    "_deleted": false,
    "_etag": "b3db0e4513c71206eb97cc2bf6dd288e9627eaa1",
    "_links": {
      "self": {
        "title": "Cpename",
        "href": "cpename/55ca2586f2c3425976c28d43"
      }
    },
    "_version": 1,
    "_latest_version": 1
  }
  ],
  "_links": {
    "parent": {
      "title": "home",
      "href": "/"
    },
  "self": {
    "title": "cpename",
    "href": "cpename?where={\"name\":\"Wordpress\"}"
  }
},
"_meta": {
  "page": 1,
  "max_results": 25,
  "total": 1
}
}

La liste des documents validant les filtres de recherche se trouve dans la liste _items . Chacun de ces documents comporte un champ _id qui contient l'identifiant de l'élément.
Dans l'exemple précédent, une seule technologie dont le nom est Wordpress a été remontée. Son identifiant est 55ca2586f2c3425976c28d43 . Les bulletins portant sur la technologie Wordpress peuvent donc être récupérés avec le filtre suivant :

/advisory?where={"cpe_names":"55ca2586f2c3425976c28d43"}

Les résultats retournés par l'API sont paginés.

Chaque page contient par défaut 25 résultats (il est possible d'en obtenir jusqu’à 50 grâce au paramètre max_results ).
Il est possible de naviguer de page en page en utilisant le paramètre page :

/advisory?page=2 , /advisory?page=3 , etc.

Récupérer des composants techniques (assets)

Il est possible de récupérer les assets traités par Serenety en effectuant une requête GET vers https://leportail.xmco.fr/api/serenety/asset.

Voici un exemple de requête cUrl pour récupérer des assets :

curl -H "Content-Type: application/json" -H "Cookie: XMSESSION=xxxxxxxxxx" 'https://leportail.xmco.fr/api/serenety/asset'

Voici un autre exemple de requête cUrl pour ne retourner que les adresses IP :

curl -g -H "Content-Type: application/json" -H "Cookie: XMSESSION=xxxxxxxxxx" 'https://leportail.xmco.fr/api/serenety/asset' --data-urlencode 'where={"type":"ipv4"}'

Les documents retournés auront la structure suivante (pour un composant/asset Serenety) :

{
"_items": [
{
"_latest_version": 1216,
"_updated": "Mon, 20 Aug 2018 07:44:49 GMT",
"_links": {
"self": {
"href": "asset/19ca3a48-67de-475e-8a6a-f4368cfaf114",
"title": "Asset"
}
},
"_id": "19ca3a48-67de-475e-8a6a-f4368cfaf114",
"_created": "Mon, 12 Dec 2016 16:36:32 GMT",
"type": "hostname",
"related_assets": [
"00bbee3e-7fd2-4917-bf5a-ce4e3d068763"
],
"tags": [
"intrusive"
],
"_version": 1216,
"value": "leportail.xmco.fr",
"_deleted": false,
"company": "14c05f9d-6b3f-4c30-8cfd-1450d7028924",
"properties": {
"ssl_protos": [
{
"protos": [
"tlsv1_1",
"tlsv1_2"
],
"port": 443,
"run": "f01a2a0f-3a55-4fc1-a82e-93cba2f33665"
}
],
"ssl_ciphers": [
{
"ciphers": {
"HIGH": [
"AES128-GCM-SHA256",
"AES128-SHA",
"AES128-SHA256",
"AES256-GCM-SHA384",
"AES256-SHA",
"AES256-SHA256",
"CAMELLIA128-SHA",
"CAMELLIA256-SHA",
"DHE-RSA-AES128-GCM-SHA256",
"DHE-RSA-AES128-SHA",
"DHE-RSA-AES128-SHA256",
"DHE-RSA-AES256-GCM-SHA384",
"DHE-RSA-AES256-SHA",
"DHE-RSA-AES256-SHA256",
"DHE-RSA-CAMELLIA128-SHA",
"DHE-RSA-CAMELLIA256-SHA",
"ECDHE-RSA-AES128-GCM-SHA256",
"ECDHE-RSA-AES128-SHA",
"ECDHE-RSA-AES128-SHA256",
"ECDHE-RSA-AES256-GCM-SHA384",
"ECDHE-RSA-AES256-SHA",
"ECDHE-RSA-AES256-SHA384"
]
},
"port": 443,
"run": "f01a2a0f-3a55-4fc1-a82e-93cba2f33665"
}
],
"ports": [
{
"banner": "Microsoft IIS httpd 7.5",
"service": "http",
"type": "tcp",
"run": "93d5abfe-966a-4c8e-8d94-6d961153256d",
"no": 80
},
{
"banner": "Le serveur",
"service": "https",
"type": "tcp",
"run": "93d5abfe-966a-4c8e-8d94-6d961153256d",
"no": 443
}
],
"ssllabs": [
{
"hpkp": false,
"cert_trusted": true,
"cert_issues": [],
"cert_transparency": true,
"mark": "A+",
"run": "f01a2a0f-3a55-4fc1-a82e-93cba2f33665",
"vulns": {
"logjam": false,
"poodleSSL": false,
"drown": false,
"crime": false,
"freak": false,
"ticketbleed": false,
"heartbleed": false,
"poodleTLS": false,
"CVE-2014-0224": false,
"CVE-2016-2107": false,
"ROBOT": false,
"beast": false
},
"cert_chain_issues": [],
"forward_secrecy": true,
"hsts": false
}
],
"ssl_cert": [
{
"valid_to": "Mon, 12 Oct 2020 00:00:00 GMT",
"wildcard": true,
"alt_names": [
"*.xmco.fr",
"xmco.fr"
],
"fingerprint": "D4:11:B2:D7:A1:C5:61:61:06:84:18:A1:16:7F:C5:1D:49:E4:6E:B5",
"cert": "-----BEGIN CERTIFICATE-----CERTIFICATE_DATA-----END CERTIFICATE-----\n",
"sig_algo": "sha256WithRSAEncryption",
"expired": false,
"symantec_untrust": false,
"run": "f01a2a0f-3a55-4fc1-a82e-93cba2f33665",
"key": "RSA 2048",
"ca_name": "Thawte TLS RSA CA G1",
"cert_name": "*.xmco.fr",
"valid": true,
"issuer_name": "C=US, O=DigiCert Inc, OU=www.digicert.com, CN=Thawte TLS RSA CA G1",
"valid_from": "Tue, 10 Jul 2018 00:00:00 GMT",
"port": 443,
"sig_is_weak": false,
"self_signed": false,
"serial": "7205890901421271680186232924221120434"
}
]
},
"_etag": "d57a66508494ae45cda60d76b0a5211dd96c2703"
},
{
"_id": "abcdefabcdefabcdefabcdef",
"...": "..."
}
],
"_links": {
"self": {
"href": "asset?where={\"value\": \"leportail.xmco.fr\", \"company\": \"14c05f9d-6b3f-4c30-8cfd-1450d7028924\"}",
"title": "asset"
},
"parent": {
"href": "/",
"title": "home"
}
},
"_meta": {
"max_results": 25,
"page": 1,
"total": 1
}
}

La structure de données de ce propriétés peut être amenée à évoluer. Le contenu de chaque propriété dépend des informations disponibles concernant l'asset.

Filtres de recherche

Ne retourner que les assets modifiés depuis le 13 février 2024 :

/serenety/asset' --data-urlencode 'where={_updated":{"$gt":"2024-02-12T23:00:00.000Z"}}'

Cette requête peut vous permettre de récupérer uniquement les assets modifiés depuis une certaine date, ce qui peut améliorer la vitesse de récupération des assets en cas de grand nombre (et que vous stockez régulièrement les résultats, par exemple pour une utilisation dans un PowerBI.)

Ne retourner que les adresses IP :

/serenety/asset' --data-urlencode 'where={"type": "ipv4"}'

Ne retourner que l'asset 'xmco.fr' (Note: il sera toujours contenu dans une liste _items) :

/serenety/asset' --data-urlencode 'where={"value":"xmco.fr"}'

Ne retourner que les assets dont le port 80 est exposé :

/serenety/asset' --data-urlencode 'where={"properties.ports.no": 80}'

Ne retourner que les assets affectés par la vulnérabilité HeartBleed :

/serenety/asset' --data-urlencode 'where={"properties.ssllabs.vulns.heartbleed":true}'

Liste des propriétés disponibles

ssl_cert : Informations sur le certificat SSL
ssl_ciphers : Informations sur les algorithmes de chiffrement supportés
ssl_protos : Informations sur les protocoles SSL supportés
ssllabs : Informations sur l'analyse SSLLabs
ports : Informations sur les services exposés
axfr : Informations sur la configuration du transfert de zone DNS
http_controls : Informations sur la configuration HTTP
dns_records : Informations sur la configuration DNS
vulns : Informations sur les vulnérabilités détectées
domain_expiration : Informations sur l'expiration du domaine GE

Pièces jointes (1)

pdf

XMCO_Le_Port....pdf
208 KB

Guide utilisateur de l'API

Limitations

Authentification

Authentification par clé d'API (recommandé)

Etape 1 : Générer une clé d'API

Etape 2 : lnclure la clé dans l'entête

Authentification classique

Etape 1 : Récupérer un cookie de session avec une requête HTTP

Etape 2 : Utiliser le cookie de session pour valider l'authentification à 2 facteurs (optionnel)

Etape 3 : Utiliser l'API avec l'aide du cookie de session customisé selon votre mode d'authentification

Plan d'action

Accéder à la liste des tickets m'étant assignée

Etape 1 : Obtenir son identifiant utilisateurs (user_id)

Etape 2 : Obtenir la liste des tickets m'étant assignés

Accéder à la liste des tickets de la société

Etape 1 : Obtenir son identifiant de la société (company_id)

Etape 2 : Obtenir la liste des tickets de la société

Accéder aux tickets liés à un module particulier (Audit, Yuno, Serenety)

Etape 1 : Obtenir son identifiant de société (company_id)

Etape 2 : Obtenir les identifiants des trackers

Etape 3 : Récupérer la liste des tickets associés au produit

Mettre à jour un ticket d'action

Etape 1 : Obtenir l'identifiant et l'etag du ticket à modifier

Etape 2 : Mettre à jour le ticket

Ajouter un commentaire sur une alerte ou un ticket d'action

Récupérer des fichiers d'une alerte ou un ticket d'action

Etape 1 : Obtenir l'identifiant de l'alerte ou du ticket d'action à modifier

Etape 2 : Obtenir le ou les fichier(s) associé(s) au ticket

Récupérer des bulletins Yuno

Format de données

Filtres de recherche

Récupérer l'identifiant d'une technologie

Pagination

Récupérer des composants techniques (assets)

Filtres de recherche

Liste des propriétés disponibles