Logbook Event Catalog REST API in Attack Surface Management
The Logbook is a change log of activity related to your assets. Patterns of event types and subtypes that appear in the logbook are due to the relationships between the events.
Logbook events are viewed in Attack Surface Management and, if you purchased the Advanced or Enterprise plans, can be queried via REST API.
To tour the Logbook page in the app, read this article.
The Censys Logbook REST API allows you to poll the logbook for changes in your attack surface that meet your interests.
To filter events in the logbook, you create an initial cursor. You use the cursor to submit a GET request to the logbook endpoint, which returns a new cursor as part of the response payload to use in the next request.
Visit our API documentation for details on methods.
This article discusses the real-world scenarios that trigger logbook events and lists related events.
All logbook events fall into 4 categories.
-
Host-related Events
-
Certificate-related Events
-
Domain-related Events
-
Storage Bucket-related Events
If a host is attributed to your organization, and that host has 1 open port with a known protocol detected, and it reports its software package and version, which has a common vulnerability ID linked to it in the CVE database, the following 5 event types (and subtypes) appear in this order in the logbook:
-
Host (Associate)
-
Port (Add)
-
Protocol (Add)
-
Software (Add)
-
Vulnerability (Add)
If that same host is removed from your organization, the domino effect results in 5 more event types (and subtypes) in the logbook:
-
Vulnerability (Remove)
-
Software (Remove)
-
Protocol (Remove)
-
Port (Remove)
-
Host (Disassociate)
Censys hosts are IP addresses. Hosts have many characteristics and properties which indicate the services in use by your organization.
Events of this type are related to the inclusion or exclusion of IP addresses in your organization’s attack surface.
Description
An IP address was added to your organization’s asset collection.
Real-World Triggers
-
An IP with no open ports in a previous scan is found to have at least 1 open port and is attributed to you.
Example: An IP that is part of a CIDR block you own opens a port.
-
An IP with open ports is associated to you because of new connections discovered between this IP and other assets belonging to your organization.
Example: Your organization begins running a hosted service in the cloud, and a DNS record points one of your domains to a cloud-owned IP address.
Description
An IP address was removed from your organization’s asset collection.
Real-World Triggers
-
An IP associated to you has no open ports in the most recent scan.
Example: An IP that is part of a CIDR block you own went offline.
-
An IP with open ports is no longer associated to you because there are no longer any connections between this asset and other assets belonging to your organization.
Example: Your cloud provider changed the IP address of a service you are running in the cloud.
-
An IP was manually removed from your organization.
Example: An IP that your organization is using to passively collect data is creating noise in your attack surface reporting, so you exclude it from your organization to mute the noise.
Events of this type relate to the ports on a host attributed to your organization.
Description
A port was removed from an IP.
Real-World Triggers
-
A port that was previously open on an IP attributed to your organization was not seen in the most recent scan.
Example: Your organization closed a port on an IP.
-
The IP is no longer associated to you.
Example: Your cloud provider changed the IP address of a service you are running in the cloud.
Events of this type are related to the application-layer protocol(s) or protocol category detected on an open port.
Description
A previously seen protocol or protocol category was removed from an IP.
Real-World Triggers
-
A protocol previously in use by 1 or more ports on an IP attributed to your organization is not detected in the most recent Censys scan.
Example: Your organization closes a port that was exposing a database protocol to the public Internet.
-
The IP is no longer associated to you.
Example: Your cloud provider changed the IP address of a service you are running in the cloud.
Events of this type relate to the software packages and versions reported by a service during a Censys scan of an IP.
Description
A software package was removed from an IP.
Real-World Triggers
-
A software package that was reported by 1 or more services on an IP attributed to your organization is no longer detected in the most recent Censys scan of that host.
Example: Your organization deployed new applications on an IP that don’t use the same software as the apps running there before.
-
The port reporting the software was removed.
Example: Your organization closed the port that exposed a service with a software reported.
-
The IP reporting the software version was removed.
Example: Your cloud provider changed the IP address of a service you are running in the cloud.
Events of this type relate to the presence of vulnerabilities in your organization’s in-use software, as gathered from the Common Vulnerabilities and Exposures list.
Description
A vulnerability was found for a host.
Real-World Triggers
-
A new CVE-ID is added to the Common Vulnerabilities and Exposures (CVE) database for a software version that is running on 1 of your organization’s hosts.
Example: CVE-2020-3339 is published and includes a list of affected software configurations, which matches a software reported by 1 of your hosts.
-
A host is found to be running a software version that has an existing CVE-ID linked to it.
Example: One of your organization’s services is running Apache 2.4.6, and 76 CVE-IDs are found in the database for that version.
Description
A vulnerability was removed from a host.
Real-World Triggers
-
A CVE-ID in the Common Vulnerabilities and Exposures (CVE) database is changed and the list of affected software configurations no longer applies to a software version that is running on 1 of your organization’s hosts.
-
The software version that the CVE-ID is issued for is no longer detected on any open ports of an IP address attributed to your organization.
-
The port reporting the software version with the vulnerability was removed.
-
The host reporting the software version with the vulnerability was removed.
Description
The information about a vulnerability changed.
Real-World Triggers
-
A CVE-ID in the Common Vulnerabilities and Exposures (CVE) database that applies to software running on 1 of your organization’s host was updated
Example: The description, severity score, or list of affected software configurations was updated for a CVE-ID.
Events of this type record the presentation of your organization’s certificates by your hosts during a TLS handshake with a Censys scanner.
Description
A certificate was linked to an IP.
Real-World Triggers
-
An IP presented a certificate in your asset collection during a scan.
Example: Using a fully qualified domain name belonging to your organization and the DNS information for the IP address it resolves to, Censys initiated a TLS handshake with the IP and was presented a certificate belonging to your organization.
Description
The link between a certificate and IP was removed.
Real-World Triggers
-
An IP that previously presented a certificate in your asset collection does not do so in the most recent scan.
Example: Your organization replaces a soon-to-expire certificate for 1 of your web services with a new one.
TLS certificates on hosts are used for verifying the identity claim of a server.
Events of this type are related to the inclusion or exclusion of TLS certificates in your organization’s attack surface.
Description
A certificate was attributed to your organization.
Real-World Triggers
-
A certificate is added to a public Certificate Transparency log and is attributed to you.
Example: The names in the various fields of a new certificate in a public CT Log point to your organization.
-
A certificate is presented by a host during scan and is attributed to you.
Example: An IP in a CIDR block your organization owns presents a previously unseen certificate during a TLS handshake.
Apex domains are root domains in the sense that they are only subdomains of a TLD (for example, com) or eTLD (for example, co.uk).
These domains often identify large portions of your Internet-facing business.
Events of this type record the inclusion or exclusion of apex domains in your organization’s attack surface.
Events of this type capture the expiration date of an apex domain attributed to your organization.
Description
The expiration date of an apex domain was changed.
Real-World Triggers
-
A WHOIS domain record for your organization’s apex domain provided a new expiration date for a registered domain.
Example: Your organization renews the registration for your marketing site before it expires.
Events of this type capture the Registrar of an apex domain attributed to your organization.
Events of this type relate to mail exchange servers found in MX records in the DNS for an apex domain attributed to your organization.
Events of this type relate to name servers found in the DNS for an apex domain attributed to your organization.
Events of this type relate to the inclusion and exclusion of fully qualified domain names in your organization’s attack surface.