Manual d'ús del API Antivirus

A continuació, s’aprofundeix en el funcionament i ús de cadascuna de les operacions del API Antivirus, amb el propòsit de brindar orientació clara i concisa, sobre els processos de configuració de les anomenades a les APIs, assegurant que se segueixin els passos adequats per a garantir una integració reeixida.

Algorismes i funcionament de l’escaneig de fitxers

En aquesta secció es detalla l’algorisme dissenyat per al API de Scan File, abastant el procés des de la petició de l’usuari fins a l’escaneig de fitxer i l’obtenció dels resultats de l’anàlisi.

Operació POST Scan-File

Llegenda:

• Petició usuari: És la petició realitzada pel client contra la API REST de l’antivirus.
• Valguda Request (ctti-validate-request): És la política encarregada de realitzar la validació del missatge d’entrada de la invocació a la API contra l’esquema generat en les operacions del disseny de la API.
• Logs d’invocació (ctti-invoke-log): És la política que s’empra per a guardar en el log la request i response de la política de Invoke per a posteriorment ser enviats al Analytics, permetent d’aquesta manera registrar més etapes del flux d’execució, podent el desenvolupador revisar la invocació abans i després de ser enviada al backend. Amb el que es permet identificar si la lògica aplicada en la API i el backend estan funcionant correctament, agilitzant la identificació i resolució d’errors, i el seu temps, ampliant la traçabilitat.
• Invocació al servidor SPE (Invoke): En aquesta part del flux es realitza la petició al servidor de SPE per a l’escaneig del fitxer adjunt en la petició.
• (Extensió) Capçaleres de seguretat: Aquesta extensió s’encarregarà d’eliminar les capçaleres de resposta que puguin contenir informació sensible.
• Finalització: Finalització del flux.
• Gestió d’errors (ctti-error-management): És la política que s’empra per a proporcionar una gestió més efectiva dels errors produïts dins del assembly del API, retornant una estructura uniformitzada i més clara per al client.

Operació POST Scan-File-Path

Llegenda:

• Espai compartit de fitxers: És l’espai on s’emmagatzemen els fitxers del client i són recuperats pel servidor de SPE, amb la informació de la ruta on es troba el fitxer, que és proporcionat pel client en la petició.
• Petició usuari: És la petició realitzada pel client contra la API REST de l’antivirus.
• Valguda Request (ctti-validate-request): És la política encarregada de realitzar la validació del missatge d’entrada de la invocació a la API contra l’esquema generat en les operacions del disseny de la API.
• Logs d’invocació (ctti-invoke-log): És la política que s’empra per a guardar en el log la request i response de la política de Invoke per a posteriorment ser enviats al Analytics, permetent d’aquesta manera registrar més etapes del flux d’execució, podent el desenvolupador revisar la invocació abans i després de ser enviada al backend. Amb el que es permet identificar si la lògica aplicada en la API i el backend estan funcionant correctament, agilitzant la identificació i resolució d’errors, i el seu temps, ampliant la traçabilitat.
• Invocació al servidor SPE (Invoke): En aquesta part del flux es realitza la petició al servidor de SPE per a l’escaneig del fitxer emmagatzemat en l’espai compartit, la ruta del qual per on es troba emmagatzemat el fitxer es facilita en la petició.
• (Extensió) Capçaleres de seguretat: Aquesta extensió s’encarregarà d’eliminar les capçaleres de resposta que puguin contenir informació sensible.
• Finalització: Finalització del flux.
• Gestió d’errors (ctti-error-management): És la política que s’empra per a proporcionar una gestió més efectiva dels errors produïts dins del assembly del API, retornant una estructura uniformitzada i més clara per al client.

Exemple d’ús de API d’Antivirus (Postman)

En aquesta secció es detalla un exemple d’ús dels serveis de les APIs d’Antivirus mitjançant l’eina Postman, des de l’obtenció del token de Gicar fins a l’escaneig d’un fitxer.

Nota: les URLs de les APIs per als diferents entorns (PRE i PRO) es poden visualitzar en la secció de disseny tècnic del API Antivirus"

Obtenció de token Gicar

Per a l’obtenció del token Gicar, és necessari invocar a la següent operació amb les següents configuracions:

EndPoints

POST

https://preproduccio.endpointma.autenticaciogicar4.extranet.gencat.cat/realms/gicarcpd4/protocol/openid-connect/token

Entrada

Cos de petició:

• client_id: *client ID de Gicar obtingut en la sol·licitud de credencials de keycloak indicat anteriorment*
• client_secret: *Client secret de Gicar obtingut en la sol·licitud de credencials de keycloak indicat anteriorment*
• grant_type: *client_credentials*

Capçaleres: Buit

Sortida:

• access_token: Conté el token d’accés de Gicar
• expiris_in: Temps de validesa del token
• token_type: Tipus del token

Obtenció de token SPE

Per a l’obtenció del token SPE, és necessari invocar a la següent operació amb les següents configuracions:

EndPoints

POST

https://preproduccio.ctti.apim.intranet.gencat.cat/ctti/privat-pre/2669/api-request-token/authentication

Entrada

Capçaleres: Buit

Capçaleres:

• Authorization: Token d’accés Gicar
• X-IBM-Client-Id: Client ID de l’aplicació subscrita al producte de APIs

Sortida:

• access_token: Conté el token d’accés de SPE
• refresh_token: Conté el token de refresh de SPE
• access_token_expiration_time: Temps de validesa del token

Refresc de token SPE

Per a refrescar el token SPE, és necessari invocar a la següent operació amb les següents configuracions:

EndPoints

POST

https://preproduccio.ctti.apim.intranet.gencat.cat/ctti/privat-pre/2669/api-request-token/refresh

Entrada

Capçaleres: Buit

• Authorization: Bearer
• X-IBM-Client-Id: Client ID de l’aplicació subscrita al producte de APIs
• Authorization-SPE: Bearer

Sortida:

• access_token: Conté el token d’accés de SPE
• refresh_token: Conté el token de refresh de SPE
• access_token_expiration_time: Temps de validesa del token

Escaneig de fitxers

Per a escanejar fitxers, és necessari invocar a la següent operació amb les següents configuracions:

EndPoints

POST

https://preproduccio.ctti.apim.intranet.gencat.cat/ctti/privat-pre/2669/api-scan-file/scan-file

Entrada

Cos de petició: form_data

• file:

Capçaleres:

• Authorization: Bearer
• X-IBM-Client-Id: Client ID de l’aplicació subscrita al producte de APIs
• Authorization-SPE: Bearer

Sortida:

• scanStatus: Indicador de si l’escaneig s’ha realitzat amb èxit o no
• fileScanned: Nom del fitxer escanejat
• fileStatus: Resultat de l’anàlisi (CLEAN)
• totalInfections: Nombre total d’infeccions detectades
• bytesScanned: Nombre de bytes escanejats
• totalFilesScanned: Nombre de fitxers escanejats

Possibles valors de resposta del API Antivirus a l’escaneig de fitxers:

Per al camp scanStatus, alguns valors típics que podries trobar-te són:

Valor	Significat
SCAN_SUCCESS	L’anàlisi es va completar correctament.
SCAN_FAILURE	L’anàlisi no va poder completar-se per algun error tècnic.

Per al camp fileStatus, els valors que podries trobar-te són:

Valor	Significat
CLEAN	L’arxiu està net, sense amenaces detectades.
FULLY_REPAIRED	S’ha detectat malware o una amenaça en l’arxiu però s’ha reparat reeixidament.
INTERNAL_SERVER_ERROR	Codi d’error genèric.
FILE_ACCESS_FAILED	No s’ha pogut accedir al fitxer (per temes de permisos o per connectivitats).
FILE_SIZE_TOO_LARGE	L’arxiu ha sobrepassat el límit d’escaneig.
NO_AV_LICENSE	No es disposa d’una llicència vàlida.
RESOURCE_UNAVAILABLE	Els recursos requerits per a escanejar no es troben disponibles.

Escaneig de fitxers per ruta

Per a escanejar fitxers facilitant la ruta per on es troba emmagatzemat els fitxers, és necessari invocar a la següent operació amb les següents configuracions:

EndPoints

POST

https://preproduccio.ctti.apim.intranet.gencat.cat/ctti/privat-pre/2669/api-scan-file/scan-file-path

Entrada

_Cos de petició: JSON

• filePath: <La ruta del fitxer a analitzar, emmagatzemat en l’espai compartit>

Capçaleres:

• Authorization: Bearer
• X-IBM-Client-Id: Client ID de l’aplicació subscrita al producte de APIs
• Authorization-SPE: Bearer

Sortida:

• scanStatus: Indicador de si l’escaneig s’ha realitzat amb èxit o no
• fileScanned: Nom del fitxer escanejat
• fileStatus: Resultat de l’anàlisi (CLEAN)
• totalInfections: Nombre total d’infeccions detectades
• bytesScanned: Nombre de bytes escanejats
• totalFilesScanned: Nombre de fitxers escanejats

Possibles valors de resposta del API Antivirus a l’escaneig de fitxers:

Per al camp scanStatus, alguns valors típics que podries trobar-te són:

Valor	Significat
SCAN_SUCCESS	L’anàlisi es va completar correctament.
SCAN_FAILURE	L’anàlisi no va poder completar-se per algun error tècnic.

Per al camp fileStatus, els valors que podries trobar-te són:

Valor	Significat
CLEAN	L’arxiu està net, sense amenaces detectades.
FULLY_REPAIRED	S’ha detectat malware o una amenaça en l’arxiu però s’ha reparat reeixidament.
INTERNAL_SERVER_ERROR	Codi d’error genèric.
FILE_ACCESS_FAILED	No s’ha pogut accedir al fitxer (per temes de permisos o per connectivitats).
FILE_SIZE_TOO_LARGE	L’arxiu ha sobrepassat el límit d’escaneig.
NO_AV_LICENSE	No es disposa d’una llicència vàlida.
RESOURCE_UNAVAILABLE	Els recursos requerits per a escanejar no es troben disponibles.

Annexos

Col·lecció POSTMAN

En aquesta secció s’inclou la col·lecció de Postman, que pot ser importada en l’eina per a comptar amb totes les peticions al API d’Antivirus prèviament configurades.

• Col·lecció Postman

API Antivirus Swagger

En aquesta secció s’inclou les especificacions YAML de les APIs d’Antivirus desenvolupades.

API Request Token

API encarregada d’oferir els serveis d’autenticació contra el servidor de SPE i refrescar el token d’accés.

• Adjuntem el fitxer ymal del API Request token (Swagger)

API Scan File

API encarregada d’oferir els serveis relacionats amb l’escaneig dels fitxers.

• Adjuntem el fitxer ymal del API Scan File (Swagger)

Configuració del token automàtic en Postman

L’eina de Postman compta amb la funcionalitat de la configuració automàtica del token OAuth 2.0 en les peticions que es realitzen, que facilitaria el procés d’invocacions contra les APIs d’Antivirus.

En aquesta secció es detalla els passos per a configurar l’obtenció automàtica del token de Gicar (Keycloak) en les peticions contra el API d’Antivirus. Els passos a realitzar són els següents:

1. Primer s’accedeix a la sección “Authorization” del Postman, i es tria l’opció OAuth 2.0 en el desplegable de “Auth Type”

   

S’emplenen els paràmetres amb els següents valors:

• Token Name: Indicar el nom del token

• Grant type: Client Credentials

• Access Token URL: https://preproduccio.endpointma.autenticaciogicar4.extranet.gencat.cat/realms/gicarcpd4/protocol/openid-connect/token

• Client ID: Client ID de GICAR

• Client Secret: Client Secret de GICAR

• Client Authentication: Send as Basic Auth header

  

2. Una vegada emplenat els paràmetres anteriors, es prem sobre el botó “Get new access token”

   

3. Després d’obtenir el token d’accés GICAR, es prem sobre el botó “Use Token” per a afegir el token en les peticions que es realitzen contra les APIs d’antivirus.