DeepSurface: API Documentation
DocumentationInstallation GuideOverviewLet DeepSurface Host For YouGetting StartedSystem RequirementsSelf Hosted Quick Start - Installing to Cloud PlatformsSelf Hosted - Installation Using an OVARegistration, Package Installation, and InitializationFirst Steps After Initialization of the ConsoleDeployment OptionsMain and Subordinate ConsolesAgent-Based DeploymentUser Managed Scan DeploymentCredentialed Scanning DeploymentMixed EnvironmentDeployment ToolsActive Directory Group PolicyMicrosoft Endpoint Configuration Manager (part of InTune)Tanium DeployHCL BigFixIvantiVirtual MachinesVMWareVirtual BoxVirtualBox Guest AdditionsAWS EC2 (BYOL)AWS EC2 (Usage Based)Azure CloudGoogle CloudAdditional Items to ConsiderMain Console Server CertificatesLDAPTOFUClock SyncDeepSurface CommandsMultiple Vulnerability SourcesAPI DocumentationUser GuideReportingDashboardsExportsRisk InsightHostsPatchesVulnerabilitiesVulnerability InstancesUsersRemediation Workflow ManagerPlansSettingsIntegrationsWorkflowExportingAccepted Risk PlansAccepted Risk WorkflowExploreModelPathsActivityTasksConfiguration AlertsScan LogsNotification SettingsScanningStatusAgentsUser ManagedCredentialed Scanning SettingsCredentialsScan GroupsGeneral SettingsCloud ScanningNetwork ConnectivitySubordinatesVulnerability SourcesSetupSensitive Assets: PolicesSensitive Assets: ManualAdmin SettingsSMTP SettingsCertificatesOutbound ProxyAuthentication ProvidersUsersTagsIntegrations GuideVulnerability SourcesCrowdStrike SpotlightSentinelOneCarbon Black CloudMicrosoft Defender for EndpointWazuhLansweeper CloudNessus APITenable.io APISecurity Center/Tenable.sc APIRapid7 InsightVM APIQualys APINozomi GuardianEclypsiumAWS InspectorRemediationJira SoftwareTanium (BETA)Authentication ProvidersLDAP (Active Directory)SAML (Azure Active Directory)SAML (Google)SAML (Okta)PAMCyberArkDelinea (Thycotic)Microsoft LAPSSecurity GuideFirewall ConfigurationBase Network RequirementsAgent Network RequirementsCredentialed Scanning Network RequirementsAPI Network RequirementsHow DeepSurface Scans WorkDomain (LDAP) ScanningHost Scanning RoutineReasons for the Administrative Access RequirementEndpoint Protection ConsiderationsOther ItemsScope of Data Storage and RetentionIPS/IDS ConsiderationsLoggingResetting the DSADMIN passwordProduct InformationChangelogsOpen source LicensesEnd User License Agreement (EULA)
This page assumes that you can reach your DeepSurface console via https://hostname
.
Please refer to the Swagger UI documentation page on your DeepSurface console. If you can reach your DeepSurface console at https://hostname
, then you can reach the Swagger UI at https://hostname/api/v1/docs
and the accompanying OpenAPI JSON specification at https://hostname/api/v1/openapi.json
.
One set of API credentials can be generated per user on the user settings page. The full set of instructions for generating these credentials is present at the top of the https://hostname/api/v1/docs
page.
To authenticate to the API programmatically:
- POST
https://hostname/api/v1/token/oauth2
with payload username=API_KEY&password=API_SECRET
where API_KEY is your API Key and API_SECRET is your API Secret.
- If authentication was successful, then the body of the response will be a JSON object that contains a key
access_token
. Extract the value and attach this to your headers as: Authorization:Bearer ACCESS_TOKEN
where ACCESS_TOKEN is the access_token value from the response JSON. Use this header for all subsequent requests.
Example shell script using curl:
ACCESS_TOKEN=$(curl -X POST --data 'username=API_KEY&password=API_SECRET' https://hostname/api/v1/token/oauth2 | python3 -c "import json;import sys;print(json.loads(sys.stdin.read())['access_token'])")
curl -X POST --header "Authorization: Bearer $ACCESS_TOKEN" --header 'Content-Type: application/json' 'https://hostname/api/v1/model/$search' -d '{}'
[
{
"created" : 1622234277.25352,
"id" : "2ac4e5c4-53fc-4b77-80fd-88948962dcf8",
"identifier" : "observed",
"label" : "Observed",
"last_analyzed" : 0,
"modified" : 1622238770.71588,
"parent" : "2ac4e5c4-53fc-4b77-80fd-88948962dcf8",
"risk" : 0
},
{
"created" : 1622234277.25352,
"id" : "4dd69d13-c9da-4e4f-b039-07c6e2594066",
"identifier" : "base",
"label" : "Base",
"last_analyzed" : 1624731840.36375,
"modified" : 1624655584.96631,
"parent" : "2ac4e5c4-53fc-4b77-80fd-88948962dcf8",
"risk" : 0
}
]