Get scan details

  7 minute read  

GET https://daas.digicert.com/apicontroller/v1/scan/getScanDetails?surveyDefId=292888&accountId=5153184&divisionId=677793
Use this endpoint to get information about an existing scan template.

For more information on discovery scan and its details, see Set up and run a scan.

Example requests and responses

cURL

curl --location --request GET 'https://daas.digicert.com/apicontroller/v1/scan/getScanDetails?surveyDefId=292888&accountId=5153184&divisionId=677793' \
--header 'X-DC-DEVKEY: {{api_key}}' \
--header 'Content-Type: application/json' \
--data-raw ''

200 OK

{
    "error": null,
    "data": {
        "accountId": "5153184",
        "divisionId": 677793,
        "surveyName": "02april2020 01",
        "frequencyType": "daily",
        "surveyDefId": 292888,
        "state": "active",
        "createdTime": 1585829323489,
        "startTime": 52200000,
        "hasVulnerability": true,
        "currentScanJobList": [{
			"startTime": 1628060456025,
			"percentageCompleted": 0.0,
			"state": 10,
			"vulStartTime": null,0
			"vulPercentageCompleted": 0.0,
			"vulState": null,
			"duration": null,
			"vulEnabled": true,
			"jobId": "368173",
			"includedSensors": [{a
				"ipInclusionList":  "www.yahoo.com,www.google.com,www.digicert.com",
				"includedPorts": ["443", "389", "636", "22", "143", "110", "465",  
                                          "8443", "3389"],
				"openPorts": null,
				"ipExclusionList": "",
				"licenseKey": "DBE32EF28E344F97",
				"includeAllSubdomains": ["www.digicert.com"],
				"selectedSubdomains": [{
					"domain": "www.yahoo.com",
					"subdomains": ["accountlink.www.yahoo.com", 
                                                  "secure.www.yahoo.com"]
				}, {
					"domain": "www.google.com",
					"subdomains": ["www.google.com----------------- 
                                                  r.reflectiz.com"]
				}],
				"ipv4Sensor": false,
				"portSelectionChoice": "default"
			}]
		}],
        "vulnerabilityScanOption": "critical",
        "surveyConfigDTO": {
            "sensorWithIpPortDTO": [
                {
                    "ipInclusionList": "www.yahoo.com,www.google.com,www.digicert.com",
                    "includedPorts": ["443", "389", "636", "22", "143", "110", "465", "8443", "3389"],
                    "openPorts": null,
                    "ipExclusionList": "",
                    "licenseKey": "DBE32EF28E344F97",
                    "includeAllSubdomains": ["www.digicert.com"],
                    "selectedSubdomains": [{
					"domain": "www.yahoo.com",
					"subdomains": ["accountlink.www.yahoo.com", 
                                                   "secure.www.yahoo.com"]
		  }, {
					"domain": "www.google.com",
					"subdomains": ["www.google.com-----------------
                                                   r.reflectiz.com"]
		  }],
                    "ipv4Sensor": false,
                    "portSelectionChoice": "default"
                }
            ],
            "startTime": 0,
            "daysToRun": [],
            "disablePing": false,
            "timezone": "5:30#chennai",
            "timeToComplete": 0,
            "vulnerabilityList": "Heartbleed,POODLE (SSLv3),FREAK,LogJam,DROWN,RC4,POODLE (TLS)",
            "emulationScans": false,
            "sni": false,
            "tls13": false,
            "ipv6": false,
            "extraTlsProtocolsDiscovery": false,
            "sshDiscovery": true,
            "osDiscoverable": false,
            "serviceDiscoverable": false,
            "monthlyRecurrenceType": "1st",
            "speed": "medium",
            "refreshHPSInventory": "always",
            "scanOption": "custom"
        },
        "isCipherScan": false,
        "emailAddresses": "cc.admin@cert-testing.com",
        "listFilteredPorts": false,
        "tags": null
    }
}

URL query parameters

NameReq/OptTypeDescription
surveyDefIdrequiredintegerSurvey definition ID of the scan. To get a list of surveyDefId values for your scans, use the scan list endpoint.
accountIdrequiredstringAccount ID.
divisionIdrequiredintegerDivision ID.

Response parameters

NameTypeDescription
errorobjectIncludes the error code if any.
dataobjectObject container for response.
.. accountIdstringAccount ID.
.. divisionIdintegerDivision ID.
surveyNamestringFriendly name provided for the scan.
**Max length:**80 characters.
frequencyTypestringAllowed values: One Time, Daily, Weekly, Monthly, Cloud
surveyDefIdintegerSurvey definition ID of the scan. To get a list of surveyDefId values for your scans, use the scan list endpoint.
.. statestringStatus of the scan.
Possible values: ACTIVE, SUSPENDED, DELETED, INPROGRESS
.. createdTimeintegerScan creation time.
.. startTimeintegerStart time for the scheduled scan.
**Format:**epoch in millisecond.
Epoch corresponds to 0 hours, 0 minutes, and 0 seconds (00:00:00) Coordinated Universal Time (UTC) on a specific date, which varies from system to system.
Example: 1596781119
Note: startTime value should be 0 when the frequencytype is onetime
.. hasVulnerabilitybooleanIf true, vulnerability discovery is enabled for the scan.
.. currentScanJobListobjectObject container for in-progress scans
.. .. startTimeintegerStart time of the current scan.
**Format:**epoch in millisecond.
Epoch corresponds to 0 hours, 0 minutes, and 0 seconds (00:00:00) Coordinated Universal Time (UTC) on a specific date, which varies from system to system.
Example: 1596781119
Note: startTime value should be 0 when the frequencytype is onetime
.. .. percentageCompletedintegerScan percentage completed.
.. .. stateintegerState of the scan.
.. .. vulStartTimeintegerVulnerability discovery start time.
Format: Timestamp in milliseconds.
Example: 5:30#chennai
.. .. vulPercentageCompletedintegerVulnerability scan percentage completed.
Possible values: 0-100%
.. .. vulStateintegerStatus of the vulnerability.
.. .. durationintegerDuration of the scan in seconds.
.. .. vulEnabledintegerWhether vulnerability is enabled. If true, vulnerability is enabled. Otherwise false.
.. .. jobIdstringScan job ID.
.. .. includedSensorsobjectObject container containing IP/port configuration details for the currently running scan.
.. .. .. ipInclusionListstringIPs to include in the scan. Supported formats are individual IPs, IP range, CIDR, and FQDNs.
Example for IP format: 104.20.67.46
Example for FQDN format: digicert.com
**Note:**Loopback IP “127.0.0.1” is not allowed to scan.
.. .. .. includedPortsarrayPorts to include in the scan. It can be individual ports or port range.
.. .. .. openPortsarrayA list of the open ports scanned. Used in scenarios where the host is unresponsive to ping.
.. .. .. ipExclusionListstringIPs to exclude in the scan. Supported formats are individual IPs, IP range, CIDR, and FQDNs.
.. .. .. licenseKeystringSensor license key to create scan.
.. .. .. includeAllSubdomainsarrayList of domains to scan all subdomains for. If a domain is in this list, the scan includes all subdomains of that domain.
.. .. .. selectedSubdomainsarrayList of objects that define which subdomains of a given domain are included in the scan.
.. .. .. .. domainstringName of the domain.
.. .. .. .. subdomainsarrayList of subdomains included in the scan for the given domain.
.. .. .. isIPv4SensorbooleanUse true if the operating system of the installed sensor runs on IPv4.
.. .. .. portSelectionChoicestringSelect the default port or choose from All/custom ports.
.. vulnerabilityScanOptionstringSetting that defines which vulnerabilities to scan for.
Allowed values: all, critical.
.. surveyConfigDTOobjectObject container for scan configuration details.
.. .. sensorWithIpPortDTOobjectObject container for IP/port configuration details.
.. .. .. ipInclusionListstringIPs to include in the scan. Supported formats are individual IPs, IP range, CIDR, and FQDNs.
Example for IP format: 104.20.67.46
Example for FQDN format: digicert.com
**Note:**Loopback IP “127.0.0.1” is not allowed to scan.
.. .. .. includedPortsstringPorts to include in the scan. It can be individual ports or port range.
.. .. .. openPortsarrayA list of the open ports scanned. Used in scenarios where the host is unresponsive to ping.
.. .. .. ipExclusionListstringIPs to exclude in the scan. Supported formats are individual IPs, IP range, CIDR, and FQDNs.
Example for IP format: 104.20.67.46
Example for FQDN format: digicert.com
**Note:**Loopback IP “127.0.0.1” is not allowed to scan.
.. .. .. licenseKeystringSensor license key to create scan.
.. .. .. .. includeAllSubdomainsarrayList of domains to scan all subdomains for. If a domain is in this list, the scan includes all subdomains of that domain.
.. .. .. .. selectedSubdomainsarrayList of objects that define which subdomains of a given domain are included in the scan.
.. .. .. .. .. domainstringName of the domain.
.. .. .. .. .. subdomainsarrayList of subdomains included in the scan for the given domain.
.. .. .. .. isIPv4SensorbooleanUse true if the operating system of the installed sensor runs on IPv4.
.. .. .. .. portSelectionChoicestringSelect the default port or choose from All/custom ports.
.. daysToRunintegerDays when the scheduled scan runs.
Possible values: 1, 2, 3, 4, 5, 6,7
Note: 1 being Sunday.
.. disablePingbooleanEnable hosts discovery that do not respond to ping.
Note: : If true, openPorts should be provided.
.. timezonestringTime zone for the scan.
Format: GMT + your timezone offset.
Example: -8#pacifictime
.. timeToCompleteintWait time to complete the scan. 0 implies no timeout.
.. vulnerabilityListstringThis is a comma separated list of the vulnerabilities to scan for.
Allowed values: Heartbleed, POODLE(SSLv3), FREAK, LogJam, DROWN, RC4, POODLE(TLS), BEAST, CRIME, BREACH, SWEET32.
.. emulationScansbooleanIf true, it will exclude Heartbleed and POODLE (TLS) from vulnerability discovery.
.. snibooleanEnable the Server Name Indication (SNI) for your scan.
.. tls13booleanEnable scan of TLS v1.3 protocol.
Default: false
.. ipv6booleanUse true if IPv6 addresses are used.
Default: false
.. extraTlsProtocolsDiscoverybooleanEnable discovery of extra TLS protocol.
Default: false
.. sshDiscoverybooleanEnable SSH key to be discovered.
Default: false
.. osDiscoverablebooleanInclude or exclude OS information.
Default: false
.. serviceDiscoverablebooleanInclude or exclude server application information.
Default: false
.. monthlyRecurrenceTypestringDay of the month specified for recurring scan.
Allowed values: 1st, 2nd, 3rd, 4th, 5th
Note: 1st being the first day of the month.
.. speedstringHow fast the scan completes.
Default: medium
Allowed values: slow, medium, fast
.. refreshHPSInventorystringHow often the host inventory will refresh. 1 – always, 2 –monthly, 0 – never
.. scanOptionstringConfigure the scan settings either to custom / optimize.
isCipherScanbooleanEnable scan for ciphers configured on server.
Default: false
emailAddressstringEmail address for the contact associated with the scan.
listFilteredPortsbooleanIf enabled, scan will list all the closed and filtered ports.
Default: false
tagsstringAdd tags to the scan. Tags can be a combination of letters (a-z or A-Z), numbers (0-9), number signs (#), or spaces. Entries must be comma-separated. (Maximum 512 characters).
Note: Alphanumeric characters like #, @ and _ are allowed.