Censys Search

the censys search connector allows for advanced search capabilities and asset management within the censys database, directly from the swimlane platform censys search is a robust cybersecurity platform that provides in depth visibility into the assets and risks present on the internet this connector enables swimlane turbine users to integrate with censys search, allowing them to add comments to hosts, create and manage tags, retrieve metadata, and conduct detailed searches for hosts and services by leveraging this integration, security teams can enhance asset management, streamline threat intelligence, and improve incident response through enriched data and automated workflows censys search empowers users with the most comprehensive, accurate, and up to date map of the internet for proactive and reactive security analysis at scale prerequisites to effectively utilize the censys search connector within swimlane turbine, ensure you have the following prerequisites http basic authentication with the following parameters url the endpoint url for the censys api api id your unique identifier for accessing the censys api api secret the secret key associated with your api id for secure authentication capabilities the censys search connector provides the following capabilities add comments about a given host create a new tag get metadata from host retrieve tags for a host returns comments about a given host search host search host by ip update a tag limitations only search and metadata actions are available for free users to access tags and comments actions, a commercial account is required api documentation for more information on censys search censys search api https //search censys io/api#/ configurations censys platform http basic authentication authenticates using username and password configuration parameters parameter description type required url a url to the target host string required username api id string required password api secret string required verify ssl verify ssl certificate boolean optional http proxy a proxy to route requests through string optional actions add comments about a given host adds a user defined comment to a host in censys using the ip address and specified content endpoint url /api/v2/hosts/{{ip}}/comments method post input argument name type required description ip string required the ip address of the requested host contents string required response content output parameter type description status code number http status code of the response reason string response reason phrase code number output field code status string status value result object result of the operation id string unique identifier ip string output field ip author id string unique identifier contents string response content created at string output field created at example \[ { "status code" 200, "response headers" { "date" "thu, 22 aug 2024 05 23 22 gmt", "content type" "application/json", "transfer encoding" "chunked", "connection" "keep alive", "access control allow origin" " ", "x content type options" "nosniff", "strict transport security" "max age=31536000; includesubdomains; preload", "access control allow credentials" "true", "access control allow methods" "put, get, post, options", "access control allow headers" "dnt,keep alive,user agent,x requested with,if modified since,cache control,conte ", "access control max age" "1728000", "cf cache status" "dynamic", "set cookie" " cf bm=iddyryf khbztvrjd5j8a772b8 tu6zrsdl5hqobgow 1724304202 1 0 1 1 a bu4qr6l ", "server" "cloudflare", "cf ray" "8b706e2cee0579e0 hyd" }, "reason" "ok", "json body" { "code" 200, "status" "ok", "result" {} } } ] create a new tag creates a new tag in censys with the specified name to improve team's asset management endpoint url /api/v2/tags method post input argument name type required description name string required name of the resource metadata object optional response data color string optional parameter for create a new tag output parameter type description status code number http status code of the response reason string response reason phrase code number output field code status string status value result object result of the operation id string unique identifier name string name of the resource metadata object response data color string output field color created at string output field created at updated at string output field updated at example \[ { "status code" 200, "response headers" { "date" "thu, 22 aug 2024 05 23 22 gmt", "content type" "application/json", "transfer encoding" "chunked", "connection" "keep alive", "access control allow origin" " ", "x content type options" "nosniff", "strict transport security" "max age=31536000; includesubdomains; preload", "access control allow credentials" "true", "access control allow methods" "put, get, post, options", "access control allow headers" "dnt,keep alive,user agent,x requested with,if modified since,cache control,conte ", "access control max age" "1728000", "cf cache status" "dynamic", "set cookie" " cf bm=iddyryf khbztvrjd5j8a772b8 tu6zrsdl5hqobgow 1724304202 1 0 1 1 a bu4qr6l ", "server" "cloudflare", "cf ray" "8b706e2cee0579e0 hyd" }, "reason" "ok", "json body" { "code" 200, "status" "ok", "result" {} } } ] get metadata from host retrieve a list of services scanned by censys, usable as 'services service name' values in search queries endpoint url /api/v2/metadata/hosts method get output parameter type description status code number http status code of the response reason string response reason phrase code number output field code status string status value result object result of the operation services array output field services example \[ { "status code" 200, "response headers" { "date" "thu, 22 aug 2024 05 23 22 gmt", "content type" "application/json", "transfer encoding" "chunked", "connection" "keep alive", "access control allow origin" " ", "x content type options" "nosniff", "strict transport security" "max age=31536000; includesubdomains; preload", "access control allow credentials" "true", "access control allow methods" "put, get, post, options", "access control allow headers" "dnt,keep alive,user agent,x requested with,if modified since,cache control,conte ", "access control max age" "1728000", "cf cache status" "dynamic", "set cookie" " cf bm=iddyryf khbztvrjd5j8a772b8 tu6zrsdl5hqobgow 1724304202 1 0 1 1 a bu4qr6l ", "server" "cloudflare", "cf ray" "8b706e2cee0579e0 hyd" }, "reason" "ok", "json body" { "code" 200, "status" "ok", "result" {} } } ] retrieve tags for host retrieves a list of tags for a specified host in censys using the unique host identifier provided endpoint url /api/v2/tags/{{id}}/hosts method get input argument name type required description id string required the unique id of the tag output parameter type description status code number http status code of the response reason string response reason phrase code number output field code status string status value result object result of the operation hosts array output field hosts ip string output field ip tagged at string output field tagged at example \[ { "status code" 200, "response headers" { "date" "thu, 22 aug 2024 05 23 22 gmt", "content type" "application/json", "transfer encoding" "chunked", "connection" "keep alive", "access control allow origin" " ", "x content type options" "nosniff", "strict transport security" "max age=31536000; includesubdomains; preload", "access control allow credentials" "true", "access control allow methods" "put, get, post, options", "access control allow headers" "dnt,keep alive,user agent,x requested with,if modified since,cache control,conte ", "access control max age" "1728000", "cf cache status" "dynamic", "set cookie" " cf bm=iddyryf khbztvrjd5j8a772b8 tu6zrsdl5hqobgow 1724304202 1 0 1 1 a bu4qr6l ", "server" "cloudflare", "cf ray" "8b706e2cee0579e0 hyd" }, "reason" "ok", "json body" { "code" 200, "status" "ok", "result" {} } } ] returns comments about a given host retrieves user generated comments for a specified host ip address in censys search endpoint url /api/v2/hosts/{{ip}}/comments method get input argument name type required description ip string required the ip address of the requested host output parameter type description status code number http status code of the response reason string response reason phrase code number output field code status string status value result object result of the operation ip string output field ip comments array output field comments id string unique identifier ip string output field ip author id string unique identifier contents string response content created at string output field created at example \[ { "status code" 200, "response headers" { "date" "thu, 22 aug 2024 05 23 22 gmt", "content type" "application/json", "transfer encoding" "chunked", "connection" "keep alive", "access control allow origin" " ", "x content type options" "nosniff", "strict transport security" "max age=31536000; includesubdomains; preload", "access control allow credentials" "true", "access control allow methods" "put, get, post, options", "access control allow headers" "dnt,keep alive,user agent,x requested with,if modified since,cache control,conte ", "access control max age" "1728000", "cf cache status" "dynamic", "set cookie" " cf bm=iddyryf khbztvrjd5j8a772b8 tu6zrsdl5hqobgow 1724304202 1 0 1 1 a bu4qr6l ", "server" "cloudflare", "cf ray" "8b706e2cee0579e0 hyd" }, "reason" "ok", "json body" { "code" 200, "status" "ok", "result" {} } } ] search host executes a search in censys for specific host or service attributes, returning a summary list of matching hosts endpoint url /api/v2/hosts/search method get input argument name type required description q string optional query used to search for hosts with matching attributes uses the censys search language per page number optional the maximum number of hits to return in each response (minimum of 1, maximum of 100) virtual hosts string optional determine how to query virtual hosts the default is exclude which will ignore any virtual hosts entries when set to include or only virtual hosts will be present in the returned list of hits, with the later returning only virtual hosts sort string optional sort the results cursor string optional cursor token from the api response, which fetches the next or previous page of hits when added to the endpoint url fields string optional comma separated list of up to 25 fields to be returned for each result (this parameter is only available to paid users) output parameter type description status code number http status code of the response reason string response reason phrase code number output field code status string status value result object result of the operation query string output field query total number output field total duration number output field duration hits array output field hits ip string output field ip location object output field location city string output field city province string output field province timezone string output field timezone country string output field country continent string output field continent postal code string output field postal code country code string output field country code coordinates object output field coordinates latitude number output field latitude longitude number output field longitude last updated at string output field last updated at autonomous system object output field autonomous system description string output field description bgp prefix string output field bgp prefix example \[ { "status code" 200, "response headers" { "content type" "application/json", "date" "thu, 01 jan 2024 00 00 00 gmt" }, "reason" "ok", "json body" { "code" 123, "status" "active", "result" {} } } ] search host by ip retrieves a detailed view of a host's services from censys using the specified ip address endpoint url api/v2/hosts/{{ip}} method get input argument name type required description ip string required the ip address of the requested host at time string optional fetches the censys view of a host and its services at the specified point in time requires historical api access nanosecond precision is allowed uses rfc3339 timestamp output parameter type description status code number http status code of the response reason string response reason phrase code number output field code status string status value result object result of the operation ip string output field ip services array output field services port number output field port service name string name of the resource transport protocol string output field transport protocol extended service name string name of the resource dns object output field dns server type string type of the resource http object output field http request object output field request method string http method to use uri string output field uri headers object http headers for the request response object output field response body string request body data protocol string output field protocol body size number request body data status code number http status code of the response status reason string status value headers object http headers for the request example \[ { "status code" 200, "response headers" { "date" "thu, 22 aug 2024 05 23 22 gmt", "content type" "application/json", "transfer encoding" "chunked", "connection" "keep alive", "access control allow origin" " ", "x content type options" "nosniff", "strict transport security" "max age=31536000; includesubdomains; preload", "access control allow credentials" "true", "access control allow methods" "put, get, post, options", "access control allow headers" "dnt,keep alive,user agent,x requested with,if modified since,cache control,conte ", "access control max age" "1728000", "cf cache status" "dynamic", "set cookie" " cf bm=iddyryf khbztvrjd5j8a772b8 tu6zrsdl5hqobgow 1724304202 1 0 1 1 a bu4qr6l ", "server" "cloudflare", "cf ray" "8b706e2cee0579e0 hyd" }, "reason" "ok", "json body" { "code" 200, "status" "ok", "result" {} } } ] update a tag updates a specific tag for a team in censys using the tag's unique identifier and a new name requires 'id' as path parameter and 'name' in json body endpoint url /api/v2/tags/{{id}} method put input argument name type required description id string required the unique id of the tag name string required name of the resource metadata object optional response data color string optional parameter for update a tag output parameter type description status code number http status code of the response reason string response reason phrase code number output field code status string status value result object result of the operation id string unique identifier name string name of the resource metadata object response data color string output field color created at string output field created at updated at string output field updated at example \[ { "status code" 200, "response headers" { "date" "thu, 22 aug 2024 05 23 22 gmt", "content type" "application/json", "transfer encoding" "chunked", "connection" "keep alive", "access control allow origin" " ", "x content type options" "nosniff", "strict transport security" "max age=31536000; includesubdomains; preload", "access control allow credentials" "true", "access control allow methods" "put, get, post, options", "access control allow headers" "dnt,keep alive,user agent,x requested with,if modified since,cache control,conte ", "access control max age" "1728000", "cf cache status" "dynamic", "set cookie" " cf bm=iddyryf khbztvrjd5j8a772b8 tu6zrsdl5hqobgow 1724304202 1 0 1 1 a bu4qr6l ", "server" "cloudflare", "cf ray" "8b706e2cee0579e0 hyd" }, "reason" "ok", "json body" { "code" 200, "status" "ok", "result" {} } } ] response headers header description example access control allow credentials http response header access control allow credentials true access control allow headers http response header access control allow headers dnt,keep alive,user agent,x requested with,if modified since,cache control,content type,range,authorization access control allow methods http response header access control allow methods put, get, post, options access control allow origin http response header access control allow origin access control max age http response header access control max age 1728000 cf cache status http response header cf cache status dynamic cf ray http response header cf ray 8b706e2cee0579e0 hyd connection http response header connection keep alive content encoding http response header content encoding gzip content type the media type of the resource application/json date the date and time at which the message was originated thu, 01 jan 2024 00 00 00 gmt server information about the software used by the origin server cloudflare set cookie http response header set cookie cf bm=iddyryf khbztvrjd5j8a772b8 tu6zrsdl5hqobgow 1724304202 1 0 1 1 a bu4qr6lcoisbxy3lfpa njlwarde rqry9rgbfkg ifabxlqfgs9dctpeccvsikgskrhdg f20prvdrtjtrq; path=/; expires=thu, 22 aug 24 05 53 22 gmt; domain= censys io; httponly; secure; samesite=none strict transport security http response header strict transport security max age=31536000; includesubdomains; preload transfer encoding http response header transfer encoding chunked x content type options http response header x content type options nosniff