GET: Work From Home Findings

Ingrid

https://api.bitsighttech.com/ratings/v1/findings/wfh

Use Work From Home (WFH) to get findings for a set of IP addresses.

See Work From Home user permissions.

Parameters

* Either the bulk_request or ips parameter is required.

bulk_request

* Either the ‘bulk_request’ or ‘ips’ parameter is required.

[Query] Filter by a previous bulk request.

Value: [String] Bulk upload unique identifiers [wfh_guid]. See GET: Bulk Work From Home Requests.

ips

* Either the ‘bulk_request’ or ‘ips’ parameter is required.

[Query] Identify the IP addresses to query.

IP addresses that belong to a non-telecommunications company in the Bitsight inventory will not return results.
IP addresses in the telecommunications industry are dynamic. The older the finding, the less likely it belongs to a single user.

Value: [Array] Up to 50 comma-separated IP addresses. See the recommended WFH IP addresses.

IPv6 not supported.

date_interval

[Query] Filter by date interval.

Value: [String]

7d
30d

risk_types

[Query] Filter by risk vectors.

Value: [String]

limit

[Query] Set the maximum number of results per query. The results might include fewer records (even zero), but not more.

Value: [Integer] Default: ↻ 100

offset

[Query] Set the starting point of the return.

Value: [Integer] 0 (zero) = Start the results from the first record in the result set.

Example Request

curl 'https://api.bitsighttech.com/ratings/v1/findings/wfh/?ips=IP_addresses' -u api_token:

Example Response

{
  "links":{
    "previous":null,
    "next":null
  },
  "count":16,
  "summaries":{
    "service_providers":[
      {
        "ips":{
          "total_count":1
        },
        "grades":[
          "NEUTRAL",
          "GOOD"
        ],
        "guid":"12345678-abcd-efgh-1234-abcdefghijkl",
        "name":"Anon Telecomm, Inc.",
        "findings":{
          "total_count":16
        }
      }
    ],
    "risk_types":[
      {
        "ips":{
          "total_count":1
        },
        "grades":[
          "NEUTRAL",
          "GOOD"
        ],
        "risk_type":"open_ports",
        "findings":{
          "total_count":11
        }
      }
    ],
    "vulnerabilities":[
      {
        "ips":{
          "total_count":1
        },
      "vulnerability":"CVE-2020-8772",
      "findings":{
        "total_count":1
      }
    }
  ],
  "request":{
    "ip_with_event_count":1,
    "requested_ip_count":1,
    "ineligible_ip_count":0,
    "requested_ips":[
      "123.123.123.123"
    ],
    "non_isp":[ ],
    "eligible_ip_count":1
  },
  "infections":[
    {
      "ips":{
        "total_count":1
      },
      "findings":{
        "total_count":7
      },
      "infection":"Rovnix"
    }
  ],
  "locations":[
    {
      "country":"United States of America",
      "grades":[
        "NEUTRAL",
        "GOOD"
      ],
      "findings":{
        "total_count":16
      },
      "country_code":"US",
      "ips":{
        "total_count":1
      }
    }
  ],
  "ips":[
    {
      "service_providers":[
        "12345678-abcd-efgh-1234-abcdefghijkl"
      ],
      "risk_types":[
        "botnet_infections",
        "vulnerability",
        "open_ports"
      ],
      "findings":{
        "total_count":16
      },
      "vulnerabilities":[
        "CVE-2019-8942",
        "CVE-2020-8772"
      ],
      "infections":[
        "Rovnix"
      ],
      "locations":[
        "US"
      ],
      "grades":[
        "NEUTRAL",
        "GOOD"
      ],
      "services":[
        "IMAP with STARTTLS",
        "HTTPS"
      ],
      "ip_address":"123.123.123.123"
    }
  ],
  "services":[
    […]
    {
      "ips":{
        "total_count":1
      },
      "grades":[
        "GOOD"
      ],
      "findings":{
        "total_count":1
      },
      "service":"SMTPS"
    }
  ],
  "non_isp":[ ]
  },
  "results":[
    {
      "entities":[
        {
          "name":"Anon Telecomm, Inc.",
          "industry_sector":"Telecommunications",
          "is_service_provider":false,
          "has_parent":false,
          "guid":"12345678-abcd-efgh-1234-abcdefghijkl"
        }
      ],
      "observation_id":"_aAAa1AA_a1aAA1A1aaAAa==",
      "country":{
        "code":"US",
        "name":"United States of America"
      },
      "collection_date":"2020-08-19",
      "forensics":{
        "host_port":80,
        "host_ip":"123.123.123.123"
      },
      "occurrences":{
        "count":2,
        "event_date":"2020-08-19",
        "first_seen":"2020-08-19 01:01:23",
        "representative_timestamp":"2020-08-19 21:04:45",
        "last_seen":"2020-08-19 21:04:45"
      },
      "event_date":"2020-08-19",
      "risk_type":"open_ports",
      "details":{
 
        ⊕ See WFH Finding Details By Risk Type
 
      }
    }
  ]
}

Response Attributes

Field				Description
links Object				Navigation for multiple pages of results. See pagination.
	previous String			The URL to navigate to the previous page of results.
	next String			The URL to navigate to the next page of results.
count Integer				The number of WFH findings.
summaries Object				A summary of WFH findings.
	service_providers Array			Service provider details.
		ips Object		IP addresses provided by this service provider.
			total_count Integer	The number of IP addresses provided by an ISP.
		grades Array		If the finding is an Open Port (`"risk_type":"open_ports"`), these record grades are included.
		guid String [`entity_guid`]		The unique identifier of the service provider.
		name String		The name of the service provider.
		findings Object		WFH findings associated with this service provider.
			total_count Integer	The number of WFH findings associated with this service provider.
	risk_types Array			WFH findings by risk type.
		ips Object		IP addresses provided by this service provider.
			total_count Integer	The number of IP addresses provided by an ISP.
		grades Array		If the finding is an Open Port (`"risk_type":"open_ports"`), these record grades are included.
		risk_type String		The slug name of this risk type.
		findings Object		WFH findings associated with this risk type.
			total_count Integer	The number of WFH findings associated with this risk type.
	vulnerabilities Array			Vulnerability WFH findings.
		ips Object		IP addresses with vulnerabilities.
			total_count Integer	The number of IP addresses with vulnerabilities.
		vulnerability String		The Common Vulnerabilities and Exposures ID (CVE ID).
		findings Object		WFH findings that are vulnerabilities.
			total_count Integer	The number of WFH findings that have vulnerabilities.
	request Object			Details of the WFH request.
		ip_with_event_count Integer		The number of IP addresses with WFH findings.
		requested_ip_count Integer		The number of requested IP addresses.
		ineligible_ip_count Integer		The number of requested IP addresses that were not eligible for WFH. IP addresses that belong to a non-telecommunications company in the Bitsight inventory will not return results. IP addresses in the telecommunications industry are dynamic. The older the finding, the less likely it belongs to a single user.
		requested_ips Array		The requested IP addresses.
		non_isp Array		Requested IP addresses that do not belong to an Internet Service Provider (ISP).
		eligible_ip_count Integer		The number of requested IP addresses that were not eligible for WFH.
	infections Array			Details of infection WFH findings.
		ips Object		IP addresses that have infections.
			total_count Integer	The number of IP addresses that have infections.
		findings Object		WFH findings that are infections.
			total_count Integer	The number of WFH findings that are infections.
		infection String		The name of this infection.
	locations Array			Location details of the WFH findings.
		country String		The name of this country.
		grades Array		If the finding is an Open Port [`"risk_type":"open_ports"`], these record grades are included.
		findings Object		Location details of the WFH findings.
			total_count Integer	The number of findings in this location.
		country_code String		The 2-letter country code of this country.
		ips Object		IP address location details of the WFH findings.
			total_count Integer	The number of IP addresses in this location.
	ips Array			IP address details of the WFH findings.
		service_providers Array [`entity_guid`]		Associated service providers.
		risk_types Array		Risk types of WFH findings in this IP address.
		findings Object		WFH finding information of the requested IP addresses.
			total_count Integer	The number of WFH findings among the requested IP addresses.
		vulnerabilities Array		Vulnerabilities of the requested IP addresses.
		infections Array		Infections among the requested IP addresses.
		locations Array		Locations of the requested IP addresses.
		grades Array		If the finding is an Open Port [`"risk_type":"open_ports"`], these record grades are included.
		services Array		Services that result with an Open Port WFH finding.
		ip_address String		The IP address of the findings.
	services Array			Services that result with an Open Port WFH finding.
		ips Object		IP address details of the services.
			total_count Integer	The number of IP services used in the IP address.
		grades Array		If the finding is an Open Port [`"risk_type":"open_ports"`], these record grades are included.
		findings Object		WFH finding details.
			total_count Integer	The number of WFH findings.
		service String		Open Port services.
	non_isp Array			IP addresses that do not belong to an Internet Service Provider (ISP).
results Array				WFH findings.
	entities Array			Service provider company details.
		name String		The name of this company.
		industry_sector String		The industry of this company.
		is_service_provider Boolean		`true` = This company is an internet service provider (ISP).
		has_parent Boolean		`true` = This company has a parent company.
		guid String [`entity_guid`]		The unique identifier of this company.
	observation_id String [`observation_id`]			The observation (finding) identifier.
	country Object			Country details.
		code String		The 2-letter country code of this country.
		name String		The name of this country.
	collection_date String [`YYYY-MM-DD`]			The date when the WFH data was compiled.
	forensics Object			Asset details.
		host_port Integer		The port number used by the host.
		host_ip String		The IP address of the host.
		domain_name String		The domain name.
	occurrences Object			Observation occurrence details.
		count Integer		The number of occurrences.
		event_date String [`YYYY‑MM‑DD`]		The date when the event occurred.
		first_seen String [`YYYY‑MM‑DD HH:MM:SS`]		The datetime when the event was first seen.
		representative_timestamp String [`YYYY‑MM‑DD HH:MM:SS`]		The datetime when the event occurred.
		last_seen String [`YYYY‑MM‑DD HH:MM:SS`]		The datetime when the event was last seen.
	event_date String [`YYYY‑MM‑DD`]			The date when the event occurred.
	risk_type String			The risk type.
	details Object			WFH finding details. WFH finding details vary by risk type [`risk_type`].

Status Codes

See the common errors and status codes.

400 – Bad Request: No IP addresses were submitted via the required ips parameter or a submitted IP address was invalid.
403 – Forbidden: Review the Work From Home Privacy Notice and ensure you have met the requirements to use Work From Home.

August 27, 2020: Now includes summaries and vulnerability information.
June 30, 2020: Initial publication.

Comments

1 comment

Vanilson Rocha
June 15, 2020 13:42

Hello, I have a problem when I try to do a search using this endpoint(https://api.bitsighttech.com/ratings/v1/findings/wfh), I got 403 unauthorized, although other endpoints are working correctly.

Can someone help me ?

my email adress: allan-magalhaes.silva.ext@bureauveritas.com.

Best regards.

0

Please sign in to leave a comment.