Create scan

  5 minute read  

POST https://daas.digicert.com/apicontroller/v1/scan/create
Use this endpoint to create a scan and get certificates and vulnerabilities.

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/create' \
--header 'X-DC-DEVKEY: {{api_key}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "surveyName": "testingscan",
    "frequencyType": "onetime",
    "surveyConfigDTO": {
        "sensorWithIpPortDTO": [
            { 
                "portSelectionChoice": "default",
                "ipInclusionList": "www.digicert.com",
                "ipExclusionList": "",
                "includedPorts": [
                    "80",
                    "443",
                    "389",
                    "636",
                    "22",
                    "143",
                    "110",
                    "465",
                    "8443",
                    "3389"
                ],
                "licenseKey": "9E205E8B61130C32",
                "name": "14MaySensor Proxy3810 (Error)",
                "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"]
	       }],
                "isIPv4Sensor": true,
                "openPorts": null
            }
        ],
        "startTime": 0,
        "timeToComplete": 0,
        "timezone": "5:30#chennai",
        "monthRecType": "1st",
        "speed": "medium",
        "refreshHPSInventory": "always",
        "isCreateFlow": true,
        "scanOption": "optimize",
        "tls13": false,
        "sshDiscovery": false,
        "sni": false,
        "vulnerabilityList": "Heartbleed,POODLE (SSLv3),FREAK,LogJam,DROWN,RC4,POODLE (TLS)",
        "isOsDiscoverable": false,
        "isServiceDiscoverable": false,
        "extraTlsProtocolsDiscovery": false,
        "ipv6": false,
        "disablePing": false,
        "emulationScans": false
    },
    "accountId": 5153184,
    "cipherScan": false,
    "divisionId": 677793,
    "emailAddresses": "cc.admin@cert-testing.com",
    "vulnerabilityScanOption": "critical",
    "listFilteredPorts": false,
    "tags": ""
}'

200 OK

{
    "error": null,
    "data": {
        "accountId": "5153184",
        "divisionId": 677793,
        "surveyDefId": 294291,
        "surveyName": "testingscan",
        "message": "Scan created successfully"
    }
}

Request parameters

NameReq/OptTypeDescription
surveyNamerequiredstringFriendly name provided for the scan.
**Max length:**80 characters.
frequencyTyperequiredstringHow often the scan will run.
Allowed values: One Time, Daily, Weekly, Monthly, Cloud
surveyConfigDTOrequiredobjectObject container for scan configuration details.
.. sensorWithIpPortDTOrequiredarrayArray of objects with IP/port configuration details.
.. .. portSelectionChoicerequiredstringSelect the default port or choose from all/custom ports.
.. .. ipInclusionListrequiredstringIPs 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.
.. .. ipExclusionListoptionalstringIPs to exclude in the scan. Supported formats are individual IPs, IP range, CIDR, and FQDNs.
.. .. includedPortsrequiredarrayPorts to include in the scan. It can be individual ports or port range.
.. .. licenseKeyrequiredstringSensor license key to create scan.
.. .. namerequiredstringName of the sensor selected.
.. .. includeAllSubdomainsrequiredarrayList of domains to scan all subdomains for. If a domain is in this list, the scan includes all subdomains of that domain.
.. .. selectedSubdomainsrequiredarrayList of objects that define which subdomains of a given domain are included in the scan.
.. .. .. domainrequiredstringName of the domain.
.. .. .. subdomainsrequiredarrayList of subdomains included in the scan for the given domain.
.. .. isIPv4SensorrequiredbooleanUse true if the operating system of the installed sensor runs on IPv4.
.. .. openPortsrequiredarrayA list of the open ports scanned. Used in scenarios where the host is unresponsive to ping.
.. startTimeoptionalintegerStart 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
.. timeToCompleteoptionalintegerWait time to complete the scan. 0 implies no timeout.
.. timezoneoptionalstringTime zone for the scan.
Format: GMT + your timezone offset.
Example: -8#pacifictime
.. monthRecTypeoptionalstringDay of the month specified for recurring scan.
Allowed values: 1st, 2nd, 3rd, 4th, 5th
Note: 1st being the first day of the month.
.. speedoptionalstringHow fast the scan completes.
Default: medium
Allowed values: slow, medium, fast
.. refreshHPSInventoryrequiredstringHow often the host inventory will refresh. 1- always,2 - monthly, 0- never
.. isCreateFlowrequiredbooleanUse true when creating a new scan, and false when updating an existing scan.
.. scanOptionoptionalstringConfigure the scan settings either to custom / optimize.
.. tls13optionalbooleanEnable scan of TLS v1.3 protocol.
Default: false
.. sshDiscoveryoptionalbooleanEnable SSH key to be discovered.
Default: false
.. snioptionalbooleanEnable the Server Name Indication (SNI) for your scan.
.. vulnerabilityListrequiredstringThis 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.
.. isOsDiscoverableoptionalbooleanInclude or exclude OS information.
Default: false
.. isServiceDiscoverablerequiredbooleanInclude or exclude server application information.
Default: false
.. extraTlsProtocolsDiscoveryoptionalbooleanEnable discovery of extra TLS protocol.
Default: false
.. ipv6optionalbooleanUse true if IPv6 addresses are used.
Default: false
.. disablePingoptionalbooleanEnable hosts discovery that do not respond to ping.
Note: If true, openPorts should be provided.
.. emulationScansoptionalbooleanIf true, it will exclude Heartbleed and POODLE (TLS) from vulnerability discovery.
accountIdrequiredstringAccount ID.
divisionIdrequiredlongDivision ID.
cipherScanoptionalbooleanEnable scan for ciphers configured on server.
Default: false
emailAddressoptionalstringEmail address for the contact associated with the scan.
vulnerabilityScanOptionoptionalstringSetting that defines which vulnerabilities to scan for.
Allowed values: all, critical.
listFilteredPortsoptionalbooleanIf enabled, scan will list all the closed and filtered ports.
Default: false
tagsoptionalstringAdd 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.

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.
.. messagestringUpdated message for scan creation.