{ "openapi": "3.2.0", "info": { "title": "HAS API", "version": "1.0.0", "summary": "Acesso programatico as vulnerabilidades, pentests e painel da sua empresa.", "description": "Use para levar achados ao seu SIEM, abrir tickets no seu backlog ou fechar o ciclo de correcao pelo seu proprio fluxo.\n\nDocumentacao: https://has.hackersec.com/docs?d=api-rest", "contact": { "name": "HackerSec", "url": "https://has.hackersec.com/docs?d=api-rest" } }, "servers": [ { "url": "https://api.hackersec.com/v1" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "dashboard", "description": "Postura de seguranca em numeros" }, { "name": "vulnerabilities", "description": "Consulta e ciclo de correcao" }, { "name": "tests", "description": "Pentests" } ], "paths": { "/dashboard": { "get": { "tags": [ "dashboard" ], "operationId": "getDashboard", "summary": "Contagem por severidade e por status, e resumo dos pentests", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Dashboard" } } } }, "401": { "description": "Chave ausente, invalida ou revogada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Contrato vencido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/vulnerabilities": { "get": { "tags": [ "vulnerabilities" ], "operationId": "listVulnerabilities", "summary": "Lista vulnerabilidades, do mais recente para o mais antigo", "parameters": [ { "name": "severity", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "info", "low", "medium", "high", "critical" ] }, "description": "Filtra por severidade. Os valores sao os mesmos que a resposta devolve." }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "reported", "in_correction", "fixed", "ignored", "retest", "not_fixed", "mitigated" ] }, "description": "Filtra por status." }, { "name": "test", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra por pentest." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 100 } }, { "name": "starting_after", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Cursor. Use o next_cursor da pagina anterior." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VulnerabilityList" } } } }, "400": { "description": "Parametro desconhecido ou valor fora da faixa. O campo param diz qual.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Chave ausente, invalida ou revogada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Contrato vencido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/vulnerabilities/{id}": { "get": { "tags": [ "vulnerabilities" ], "operationId": "getVulnerability", "summary": "Uma vulnerabilidade, com evidencias e comentarios", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VulnerabilityDetail" } } } }, "401": { "description": "Chave ausente, invalida ou revogada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "O recurso esta fora do alcance desta chave", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/vulnerabilities/{id}/status": { "post": { "tags": [ "vulnerabilities" ], "operationId": "updateVulnerabilityStatus", "summary": "Muda o status da vulnerabilidade", "description": "ignored e mitigated exigem justification, de 50 a 2800 caracteres. Sao declaracoes do cliente e o texto sai no relatorio em PDF ao lado da vulnerabilidade.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "status" ], "additionalProperties": false, "properties": { "status": { "type": "string", "enum": [ "reported", "in_correction", "ignored", "mitigated", "retest" ] }, "justification": { "type": "string", "minLength": 50, "maxLength": 2800, "description": "Obrigatorio para ignored e mitigated." } } } } } }, "responses": { "200": { "description": "Vulnerabilidade atualizada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VulnerabilityDetail" } } } }, "400": { "description": "Status invalido, justificativa ausente ou fora do tamanho, ou campo desconhecido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Chave ausente, invalida ou revogada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Chave read em operacao de escrita, ou contrato vencido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "O recurso esta fora do alcance desta chave", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "A operacao conflita com o estado atual", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/vulnerabilities/{id}/retest": { "post": { "tags": [ "vulnerabilities" ], "operationId": "requestRetest", "summary": "Pede reteste da vulnerabilidade", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "context": { "type": "string", "maxLength": 2000, "description": "O que mudou. Opcional, e ajuda quem vai retestar." } } } } } }, "responses": { "200": { "description": "Reteste solicitado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VulnerabilityDetail" } } } }, "400": { "description": "Campo desconhecido no corpo", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Chave ausente, invalida ou revogada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Chave read em operacao de escrita, ou contrato vencido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "O recurso esta fora do alcance desta chave", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Ja existe um reteste pendente para esta vulnerabilidade", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/vulnerabilities/{id}/export": { "post": { "tags": [ "vulnerabilities" ], "operationId": "exportVulnerability", "summary": "Envia a vulnerabilidade para a integracao configurada", "description": "Exige integracao configurada na empresa e chave de um master.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "integration": { "type": "string", "enum": [ "jira", "servicenow", "slack", "teams", "github", "freshservice", "azuredevops", "webhook", "all" ], "default": "all" } } } } } }, "responses": { "200": { "description": "Disparada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Export" } } } }, "400": { "description": "Integracao nao configurada para esta empresa, ou campo desconhecido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Chave ausente, invalida ou revogada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Chave read em operacao de escrita, contrato vencido, ou a chave nao e de um master", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "O recurso esta fora do alcance desta chave", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Nenhuma integracao configurada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "A integracao recusou o disparo", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/tests": { "get": { "tags": [ "tests" ], "operationId": "listTests", "summary": "Lista pentests, do mais recente para o mais antigo", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 100 } }, { "name": "starting_after", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TestList" } } } }, "400": { "description": "Parametro desconhecido ou valor fora da faixa", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Chave ausente, invalida ou revogada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Contrato vencido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/tests/{id}": { "get": { "tags": [ "tests" ], "operationId": "getTest", "summary": "Um pentest, com escopo", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TestDetail" } } } }, "401": { "description": "Chave ausente, invalida ou revogada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "O recurso esta fora do alcance desta chave", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Chave secreta da empresa, criada em Configuracoes > Integracoes > API. Formato: hackersec_has_sk_..." } }, "schemas": { "Vulnerability": { "type": "object", "properties": { "object": { "type": "string", "const": "vulnerability" }, "id": { "type": "string", "description": "O mesmo identificador que aparece na plataforma" }, "name": { "type": "string", "description": "Tipo tecnico e impacto curto" }, "target": { "type": "string", "description": "Ativo exato onde a falha foi confirmada" }, "severity": { "type": "string", "enum": [ "info", "low", "medium", "high", "critical" ] }, "status": { "type": "string", "enum": [ "reported", "in_correction", "fixed", "ignored", "retest", "not_fixed", "mitigated" ] }, "cvss_score": { "type": [ "number", "null" ] }, "cvss_vector": { "type": [ "string", "null" ], "description": "CVSS 4.0" }, "cwe": { "type": [ "string", "null" ], "description": "Classificacao CWE da fraqueza, no formato CWE-", "example": "CWE-79" }, "test": { "type": "string", "description": "id do pentest em que foi encontrada" }, "reported_at": { "type": [ "string", "null" ], "format": "date-time" }, "fixed_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "VulnerabilityDetail": { "allOf": [ { "$ref": "#/components/schemas/Vulnerability" }, { "type": "object", "properties": { "description": { "type": "string" }, "remediation": { "type": "string" }, "references": { "type": "string" }, "financial_impact": { "type": "integer", "description": "Estimativa de impacto financeiro" }, "evidence": { "type": "array", "items": { "$ref": "#/components/schemas/Evidence" } }, "comments": { "type": "array", "items": { "$ref": "#/components/schemas/Comment" } } } } ] }, "Evidence": { "type": "object", "properties": { "object": { "type": "string", "const": "evidence" }, "content": { "type": "string" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "Comment": { "type": "object", "properties": { "object": { "type": "string", "const": "comment" }, "author": { "type": "string" }, "content": { "type": "string" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "Test": { "type": "object", "properties": { "object": { "type": "string", "const": "test" }, "id": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "asset_type": { "type": "string" }, "level": { "type": "string", "enum": [ "ai_native", "ai_first" ] }, "status": { "type": "string", "enum": [ "requested", "in_progress", "paused", "retest", "completed", "archived" ] }, "assets": { "type": "array", "items": { "type": "string" } }, "vulnerabilities": { "$ref": "#/components/schemas/SeverityCounts" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "started_at": { "type": [ "string", "null" ], "format": "date-time" }, "ended_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "TestDetail": { "allOf": [ { "$ref": "#/components/schemas/Test" }, { "type": "object", "properties": { "scope": { "type": "string", "description": "Briefing do teste: objetivo, cobertura e regras de engajamento.", "example": "Objetivo:\nPentest graybox nos webservices e na API do SOC." } } } ] }, "SeverityCounts": { "type": "object", "properties": { "info": { "type": "integer" }, "low": { "type": "integer" }, "medium": { "type": "integer" }, "high": { "type": "integer" }, "critical": { "type": "integer" } } }, "Dashboard": { "type": "object", "properties": { "object": { "type": "string", "const": "dashboard" }, "vulnerabilities": { "type": "object", "properties": { "total": { "type": "integer" }, "open": { "type": "integer" }, "by_severity": { "$ref": "#/components/schemas/SeverityCounts" }, "by_status": { "type": "object", "properties": { "reported": { "type": "integer" }, "in_correction": { "type": "integer" }, "fixed": { "type": "integer" }, "ignored": { "type": "integer" }, "retest": { "type": "integer" }, "not_fixed": { "type": "integer" }, "mitigated": { "type": "integer" } } } } }, "tests": { "type": "object", "properties": { "total": { "type": "integer" }, "active": { "type": "integer" }, "completed": { "type": "integer" } } } } }, "VulnerabilityList": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Vulnerability" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } } }, "TestList": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Test" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } } }, "Export": { "type": "object", "properties": { "object": { "type": "string", "const": "export" }, "vulnerability": { "type": "string" }, "integration": { "type": "string" }, "dispatched": { "type": "boolean" } } }, "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" } } }, "request_id": { "type": "string" } } } } } }