Censys Attack Surface Management

the censys connector enables seamless integration with censys attack surface management, allowing users to automate the retrieval of risk events, logbook entries, and asset inventories censys attack surface management provides comprehensive visibility into the digital assets of an organization, enabling security teams to discover and monitor assets, assess risks, and detect vulnerabilities the connector facilitates seamless integration with swimlane turbine, empowering users to automate asset inventory retrieval, logbook entry collection, and risk event and instance analysis by leveraging this connector, end users can enhance their security posture with up to date asset intelligence and proactive risk management, directly within their security workflows censys attack surface management connector integrates with the censys attack surface management platform it is used to manage and interact with the censys api, providing capabilities such as data enrichment and threat intelligence limitations none to date supported versions censys attack surface management connector supports the censys attack surface management api version specified in the connector yaml connector/connector yaml additional docs for more information, refer to the censys api documentation https //app censys io/api docs prerequisites to effectively utilize the censys attack surface management connector within swimlane turbine, ensure you have the following prerequisites api key authentication url the endpoint url for the censys api censys api key your unique api key provided by censys to access their services configuration authentication methods censys attack surface management connector supports the following authentication methods censys attack surface management api key authentication setup instructions this api uses json as the data exchange format standard http status codes are used to indicate successes (200s), client errors (400s), and server errors (500s) all request body types, request query/path parameter types, and response types are described in this spec all requests require a censys api key header containing your team's api key navigate to the censys attack surface management platform obtain your censys api key from the platform configure the connector with the obtained api key in the apikey yaml connector/config/assets/apikey yaml file troubleshooting tips ensure the api key is correct and has the necessary permissions verify that the url is correctly configured and accessible capabilities censys attack surface management connector provides the following capabilities get inventory get logbook get risk events get risk instances get inventory retrieve the current inventory of assets from censys attack surface management for analysis and monitoring get logbook get logbook entries by querying this endpoint since the amount of logbook data may be significant, multiple calls to this endpoint could be required to collect all the data matching the filters you provide note the nextcursor will always be set, regardless if the event array is empty or doesn't have the maximum number of events here's some pseudo code demonstrating how this might be accomplished initialcursor = getlogbookcursor({ filter yourfilterobject }) response = getlogbookdata({ cursor initialcursor }) results = response events while (!response endofevents) { response = getlogbookdata({ cursor response nextcursor }) results addall(response events) } all results for the given filters should now be in the results variable get risk events get all risk events by querying this endpoint there may be a significant number of entries, so pagination may be required to collect all of the information the returned data is sorted by date, with the most recent events last this, along with the pagination implementation, should allow for efficient querying of all risk events and monitoring for new events example usage to get all risk events and then watch for new events get https //app censys io/api/v2/risk events?start=2022 04 04t00 00 00z process the response and save the cursor returned in the next field for future use until we receive a response with endofevents true get https //app censys io/api/v2/risk events?cursor=\<cursor> process the response and save the cursor returned in the next field for future use some time later resume requesting events with the last used cursor you can also request that the content be presented in csv form to request csv form, make a request with the accept text/csv header note there will no longer be a cursor to resume with note that the csv set of columns is somewhat dynamic depending particularly on what fields are encountered in the delta response object results risk events each event is represented by an object with details about the changes id will contain a numeric id uniquely identifying the risk event for the workspace ts rfc3339 encoded timestamp of the risk event op what sort of operation was performed one of open , update , close open the item was created update something about the item was changed close the item was "closed" (generally only relevant for risk instances) src identifier for the source of the event one of system , api , ui srcid optional free form identifier for the specific source for src = ui this will typically be the name of the user that caused the change reason optional free form string describing why the change was made delta object the delta object describes what sort of change was made typically including details on what columns were updated or metadata changes were made example delta fields severity risk type or instance severity was changed to this value userstatus risk instance was either muted (set to muted ) or un muted (set to empty) note in csv format un muted is impossible to differentiate from other changes due to null mapping to "" enabled risk type was enabled or disabled metadata added risk instances had this sequence of metadata items added (list of json objects) metadata removed risk instances had this sequence of metadata items removed (list of json objects) get risk instances get all active risk instances in your attack surface to replicate the results in the /search endpoint, you would use the query filter "and" \[ \["type enabled", "=", true], \["status", "=", "open"], \["user status", "=", null] ] parameters get https //app censys io/api/v2/risk instances query parameters includeevents=true set to include risk type events results the result is either a json object or a csv to request the csv format include the header accept text/csv in the request the data will be formatted as a csv with a header row to help process the data (since the column ordering is undefined) see the openapi example data for what the json/csv could look like the json object format will include the following two fields total the total number of risks risks an array containing the risk data risk instance properties each risk instance will have the following properties listed id identifier for this specific risk instance typeid risk type identifier context context object describing where the risk was found displayname human readable display name severity risk severity (critical/high/medium/low) status "open" if the risk is observed, "closed" if the risk is no longer observed userstatus "muted" if the risk is considered "accepted" and should be hidden from most ui firstcomputedat rfc3339 encoded timestamp of when the risk was first observed in the workspace lastupdatedat rfc3339 encoded timestamp of when the risk instance data was updated lastcomputedat rfc3339 encoded timestamp of the most recent time the risk was observed categories an array of risk categories risk categories are organized hierarchically, ex \["top level", "category", "sub category"] in the user interface, the category is what is presented metadata an array of custom risk metadata properties events an array of associated risk events (only if includeevents=true set) hostdata json object of the host data associated with the risk instance (only if includehostdata=true set) returns data for the port the risk was found on if host data cannot be reached, or the risk lacks an ip and port, a null value will be returned matchcontext json object of additional details from the fingerprint match this can include derived data from the host, or important information from the host used to make the match match context details beta this data structure is currently subject to change the optional matchcontext field is a json object that has two keys associated with a json dict found indicates a property of the service that we found to match the risk on and its value want indicates a property of a service that we would like to see on it for example, for a software end of life risk, we could have the following matchcontext value { "found" { "services software version" "3 4 1" }, "want" { "service software version" "3 7 0" } } for a service exposed risk, we could have the following { "found" { "service name" "mysql" } } risk context host risk context when a context contains the type "host" then the risk is located on a host all host risks ip the ip address that the risk was found on name the name used to lookup the host such as for sni / host header may be "" if no name used service risks transport the transport protocol used, ex tcp , udp , quic port the port the service was found on service the name of the service, ex http , https , ssh software risks cpe the software cpe identifier, ex cpe 2 3\ a php 7 1 33 domain risk context when a context contains the type "domain" then the risk is located on a registered domain the name field of the context object contains the domain name storage bucket risk context when a context contains the type "bucket" then the risk is located on a cloud storage bucket the cri field of the context object contains censys resource identifier for the storage bucket examples include cri\ bucket\ aws\ s3\ customer test cri\ bucket\ gcp\ gcs\ customer staging cri\ bucket\ azure\ blob\ myaccount\ some container risk metadata properties risk instances can have metadata attached to them metadata items are treated as individual pieces of data that are linked to risk instances a metadata item is defined as having at least a src and potentially a srcid this pair of identifiers helps with managing system and api provided metadata an example piece of useful metadata is one computed to attach cloud/cdn/classification data to risk instances { "src" "system", "srcid" "cloud info", "cdn" "cloudflare", "classification" null, "cloud" "cloudflare inc" } risk instance events if the includeevents=true flag was set, then each risk instance will include events associated with it in the events array field each event is represented by an object with details about the changes id will contain a numeric id uniquely identifying the risk event for the workspace ts rfc3339 encoded timestamp of the risk event op what sort of operation was performed one of open , update , close open the item was created update something about the item was changed close the item was "closed" src identifier for the source of the event one of system , api , ui srcid optional free form identifier for the specific source for src = ui this will typically be the name of the user that caused the change reason optional free form string describing why the change was made risk instance host data if the includehostdata=true flag was set, then the risk instance will include the host data associated with it in the hostdata field the hostdata will be a json object containing the censys search data for the host and port the risk was found on if host data cannot be reached, or the risk lacks an ip and port, a null value will be returned for more information on the returned host data, see the censys search api documentation delta object the delta object describes what sort of change was made typically including details on what columns were updated or metadata changes were made example delta fields severity risk type or instance severity was changed to this value userstatus risk instance was either muted (set to muted ) or un muted (set to empty) note in csv format un muted is impossible to differentiate from other changes due to null mapping to "" enabled risk type was enabled or disabled metadata added risk instances had this sequence of metadata items added (list of json objects) metadata removed risk instances had this sequence of metadata items removed (list of json objects) configurations censys attack surface management authentication authenticates using an api key configuration parameters parameter description type required url a url to the target host string required censys api key censys api key string required verify ssl verify ssl certificate boolean optional http proxy a proxy to route requests through string optional actions get inventory retrieve the current inventory of assets from censys attack surface management for analysis and monitoring endpoint url /api/inventory/v1 method get input argument name type required description workspaces array optional workspaces to search across query string optional the raw censys dsl query string pagesize number optional how many hits to return cursor string optional workspaces to search across sort array optional a list of fields to sort on by default, these fields will be sorted in asc order to sort in desc order, prepend a ' ' to the field name, ie ' tags' fields array optional a list of fields to include in response hits if this field is empty, a default set of fields will be used note some large fields (like http bodies) are disallowed output parameter type description status code number http status code of the response reason string response reason phrase hits array output field hits nextcursor string output field nextcursor previouscursor string output field previouscursor querydurationmillis number output field querydurationmillis totalhits number output field totalhits example \[ { "status code" 200, "response headers" { "date" "mon, 25 nov 2024 06 17 22 gmt", "content type" "application/json", "content encoding" "gzip", "connection" "keep alive", "strict transport security" "max age=2592000; includesubdomains; preload", "cf cache status" "dynamic", "traceparent" "00 aa92bbf9fbce52fbf534d2d52d3721a9 bcb7c162a53f6519 01", "server" "cloudflare", "cf ray" "8e7f83e73c6a1bdc bom" }, "reason" "ok", "json body" { "hits" \[], "nextcursor" "string", "previouscursor" "string", "querydurationmillis" 0, "totalhits" 0 } } ] get logbook gather logbook entries from censys attack surface management, which may involve several calls to collect all data endpoint url /api/v1/logbook method get input argument name type required description cursor string optional a logbook cursor generated by /api/v1/logbook cursor output parameter type description status code number http status code of the response reason string response reason phrase events array output field events file name string name of the resource file string output field file nextcursor string output field nextcursor endofevents boolean output field endofevents example \[ { "status code" 200, "response headers" { "date" "tue, 05 nov 2024 06 36 09 gmt", "content type" "application/json; charset=utf 8", "transfer encoding" "chunked", "connection" "keep alive", "vary" "origin", "access control allow origin" " ", "x ratelimit limit" "60000", "x ratelimit remaining" "59999", "x ratelimit reset" "tue nov 05 2024 06 37 08 gmt+0000 (coordinated universal time)", "censys response type" "ok", "surrogate control" "no store", "cache control" "no store, no cache, must revalidate, proxy revalidate", "pragma" "no cache", "expires" "0", "strict transport security" "max age=2592000; includesubdomains; preload" }, "reason" "ok", "json body" { "events" \[], "nextcursor" "eyjmawx0zxiiont9lcjzdgfydci6mx0=", "endofevents" true } } ] get risk events retrieve all risk events from censys attack surface management, with support for pagination on large datasets endpoint url /api/v2/risk events method get input argument name type required description start string optional start time (inclusive) of events to query for rfc3339 formatted, ex 2022 04 01t04 00 00z end string optional end time (inclusive) of events to query for afterid number optional risk event id to query for events after limit number optional number of events to include in a page 0 indicates use the default of 50,000 cursor string optional cursor value to continue collecting events started in a previous request output parameter type description status code number http status code of the response reason string response reason phrase total number output field total next string output field next events array output field events id number unique identifier ts string output field ts op string output field op src string output field src delta object output field delta config object output field config cdn object output field cdn value array value for the parameter cloud object output field cloud value array value for the parameter classification object output field classification value array value for the parameter enabled object output field enabled risktype string type of the resource endofevents boolean output field endofevents example \[ { "status code" 200, "response headers" { "date" "tue, 05 nov 2024 06 40 50 gmt", "content type" "application/json; charset=utf 8", "transfer encoding" "chunked", "connection" "keep alive", "strict transport security" "max age=2592000; includesubdomains; preload", "cf cache status" "dynamic", "set cookie" " cf bm=jf8o1u9tfi6mruydlo1ifmvpf7uitfczp1ypiqm5xa8 1730788850 1 0 1 1 ku2yegizw\ ", "server" "cloudflare", "cf ray" "8ddadacb096047c9 bom", "content encoding" "gzip" }, "reason" "ok", "json body" { "total" 1, "next" "eyjhznrlckleijoxlcjsaw1pdci6ntawmdb9", "events" \[], "endofevents" true } } ] get risk instances retrieve all active risk instances within your censys attack surface management attack surface endpoint url /api/v2/risk instances method get input argument name type required description includeevents boolean optional if the includeevents=true flag was set, then each risk instance will include events associated with it in the events array field includehostdata boolean optional if the includehostdata=true flag was set, then the risk instance will include the host data associated with it in the hostdata field the hostdata will be a json object containing the censys search data for the host and port the risk was found on if host data cannot be reached, or the risk lacks an ip and port, a null value will be returned output parameter type description status code number http status code of the response reason string response reason phrase total number output field total risks array output field risks file name string name of the resource file string output field file example \[ { "status code" 200, "response headers" { "date" "tue, 05 nov 2024 06 37 51 gmt", "content type" "application/json; charset=utf 8", "content length" "22", "connection" "keep alive", "strict transport security" "max age=2592000; includesubdomains; preload", "cf cache status" "dynamic", "set cookie" " cf bm=amomjnnbsauu5hz2spti5tm81wgb6segvu4d ne0np4 1730788671 1 0 1 1 clgxuiz33 ", "server" "cloudflare", "cf ray" "8ddad665cdf947c9 bom" }, "reason" "ok", "json body" { "total" 0, "risks" \[] } } ] response headers header description example access control allow origin http response header access control allow origin cache control directives for caching mechanisms no store, no cache, must revalidate, proxy revalidate censys response type http response header censys response type ok cf cache status http response header cf cache status dynamic cf ray http response header cf ray 8ddad3e65fa647c9 bom connection http response header connection keep alive content encoding http response header content encoding gzip content length the length of the response body in bytes 22 content type the media type of the resource application/json; charset=utf 8 date the date and time at which the message was originated tue, 05 nov 2024 06 37 51 gmt expires the date/time after which the response is considered stale 0 pragma http response header pragma no cache server information about the software used by the origin server cloudflare set cookie http response header set cookie cf bm=9k0obh2ocffbjjgtdk7e1xixnw6sgxk5dhmxd6cvmlq 1730788569 1 0 1 1 kjxq52g xaok5rb2cbps velu bqssveq7iram4bvkxmlnvcdory6stm4fhdd3vu957qaxf7kbxrip cc3u68q; path=/; expires=tue, 05 nov 24 07 06 09 gmt; domain= censys io; httponly; secure; samesite=none strict transport security http response header strict transport security max age=2592000; includesubdomains; preload surrogate control http response header surrogate control no store traceparent http response header traceparent 00 aa92bbf9fbce52fbf534d2d52d3721a9 bcb7c162a53f6519 01 transfer encoding http response header transfer encoding chunked vary http response header vary origin x frame options http response header x frame options sameorigin x ratelimit limit the number of requests allowed in the current rate limit window 60000 x ratelimit remaining the number of requests remaining in the current rate limit window 59999 x ratelimit reset the time at which the current rate limit window resets tue nov 05 2024 06 37 08 gmt+0000 (coordinated universal time)