Logbook REST API Event Catalog

The Logbook is a changelog of activity related to your assets. The relationships between the events create patterns of event types and subtypes that appear in the logbook.

Logbook events can be viewed in the ASM web console. If you are an ASM Advanced or Enterprise user, you can query the logbook via the REST API.

Logbook API

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.

Logbook Event categories

All logbook events fall into four categories.

Host-related Events
Certificate-related Events
Domain-related Events
Storage Bucket-related Events

Example: Scenario showing relationships between events

If a host is attributed to your organization, and that host has one open port with a known protocol detected. It reports its software package and version, which has a common vulnerability ID linked to it in the CVE database; the following five event types (and subtypes) appear in this order in the logbook:

Host (Associate)
Port (Add)
Protocol (Add)
Software (Add)
Vulnerability (Add)

Host-related Events

Censys hosts are IP addresses. Hosts have many characteristics and properties that indicate the services in use by your organization.

`HOST`

These events relate to the inclusion or exclusion of IP addresses from your organization’s attack surface.

Subtype	Description	Real-World Triggers
ASSOCIATE	An IP address was added to your organization’s asset collection.	An IP with no open ports in a previous scan is found to have at least one 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.
DISASSOCIATE	An IP address was removed from your organization’s asset collection.	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 collect data passively is creating noise in your attack surface reporting, so you exclude it from your organization to mute the noise.

Cascading Event Types that can follow a Host Event
Subtype matches the Host event (for example, Host Associate is followed by Add events, and Host Disassociate is followed by Remove events). `HOST_PORT` `HOST_PROTOCOL` `HOST_SOFTWARE` `HOST_VULNERABILITY` `HOST_CERT`

Cascading Event Types that can follow a Host Event

Subtype matches the Host event (for example, Host Associate is followed by Add events, and Host Disassociate is followed by Remove events).

HOST_PORT

HOST_PROTOCOL

HOST_SOFTWARE

HOST_VULNERABILITY

HOST_CERT

`HOST_PORT`

These events are related to the application-layer protocol(s) or protocol category detected on an open port.

Subtype	Description	Real-World Triggers
ADD	A new port was added to an IP.	An IP attributed to your organization has an open port that was not open in the most recent Censys scan. Example: Your organization exposed a new service to the Internet on a port.
REMOVE	A port was removed from an IP.	The most recent scan did not find a previously open port on an IP attributed to your organization. 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.

Cascading Event Types that could follow a Port Event
Subtype matches the Port event. `HOST_PROTOCOL` `HOST_SOFTWARE` `HOST_VULNERABILITY` `HOST_CERT`

Cascading Event Types that could follow a Port Event

Subtype matches the Port event.

HOST_PROTOCOL

HOST_SOFTWARE

HOST_VULNERABILITY

HOST_CERT

`HOST_PROTOCOL`

These events are related to the application-layer protocol(s) or protocol category detected on an open port.

Subtype	Description	Real-World Triggers
ADD	A protocol or protocol category was added to an IP.	Censys scanners detect a new application-layer protocol on one or more ports of an IP attributed to your organization. Example: A web server communicates using HTTP on a port.
REMOVE	A previously seen protocol or protocol category was removed from an IP.	A protocol previously in use by one 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.

Cascading Event Types that can follow a Protocol Event
Subtype matches the Protocol event. `HOST_SOFTWARE` `HOST_VULNERABILITY`

Cascading Event Types that can follow a Protocol Event

Subtype matches the Protocol event.

HOST_SOFTWARE

HOST_VULNERABILITY

`HOST_SOFTWARE`

These events relate to the software packages and versions reported by a service during a Censys scan of an IP.

Subtype	Description	Real-World Triggers
ADD	A software package was added to an IP.	A software package is parsed from scan data of one or more ports on an IP attributed to your organization. Example: A web server reports its software as "Microsoft-HTTPAPI v:2.0" for the first time.
REMOVE	A software package was removed from an IP.	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 doesn’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.

Cascading Event Types that can follow a Protocol Event
`HOST_VULNERABILITY`

`HOST_VULNERABILITY`

These events relate to the presence of vulnerabilities in your organization’s in-use software, as gathered from the Common Vulnerabilities and Exposures list.

Subtype	Description	Real-World Triggers
ADD	A vulnerability was found for a host.	A new CVE-ID has been added to the Common Vulnerabilities and Exposures (CVE) database for a software version running on one of your organization’s hosts. Example: CVE-2020-3339 has been published and includes a list of affected software configurations, which matches a software version reported by one of your hosts. The host is found to be running a software version with an existing CVE-ID linked to it. Example: One of your organization’s services runs Apache 2.4.6, and the database contains 76 CVE-IDs for that version.
REMOVE	A vulnerability was removed from a host.	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 one of your organization’s hosts. The software version for which the CVE-ID is issued is no longer detected on 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.
CHANGE	The information about a vulnerability changed.	A CVE-ID in the Common Vulnerabilities and Exposures (CVE) database that applies to software running on one of your organization’s hosts was updated. Example: The description, severity score, or list of affected software configurations was updated for a CVE-ID.

`HOST_CERT`

These events record the presentation of your organization’s certificates by your hosts during a TLS handshake with a Censys scanner.

Subtype	Description	Real-World Triggers
ADD	A certificate was linked to an IP.	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.
REMOVE	The link between a certificate and IP was removed.	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 one of your web services with a new one. Example: Your organization closed the port that exposed a service with a software reported.

Certificate-related Events

Transport Layer Security (TLS) certificates on hosts are used for verifying the identity claim of a server.

`CERTIFICATE`

These events are related to the inclusion or exclusion of TLS certificates in your organization’s attack surface.

Subtype	Description	Real-World Triggers
ASSOCIATE	A certificate was attributed to your organization.	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.
DISASSOCIATE	This event is only generated if there are no longer any connections between a certificate and other assets belonging to your organization.

Cascading Event Types that can follow a Certificate Event
`HOST_CERT`

Domain-related Events

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.

`DOMAIN`

These events record the inclusion or exclusion of apex domains in your organization’s attack surface.

Subtype	Description	Real-World Triggers
ADD	An apex domain was added to your organization.	A domain name in a DNS name server is attributed to you. A domain listed in the names section of one of your organization’s certificates is attributed to you.
REMOVE	An apex domain was removed from your organization.	A domain is not attributed to your organization because there are no longer any connections between this name and your organization’s other assets. A domain is manually removed from your organization.

Cascading Event Types that could follow a Certificate Event
Subtype matches the Port event. `DOMAIN\_EXPIRATION\_DATE` `OMAIN\_REGISTRAR` `DOMAIN\_MAIL\_EXCHANGE\_SERVER` `DOMAIN\_NAME\_SERVER`

Cascading Event Types that could follow a Certificate Event

Subtype matches the Port event.

DOMAIN\_EXPIRATION\_DATE

OMAIN\_REGISTRAR

DOMAIN\_MAIL\_EXCHANGE\_SERVER

DOMAIN\_NAME\_SERVER

`DOMAIN_EXPIRATION_DATE`

These events capture the expiration date of an apex domain attributed to your organization.

Subtype	Description	Real-World Triggers
ADD	An expiration date was found for a domain.	A WHOIS domain record for your organization’s apex domain provided the expiration date of the registration.
REMOVE	An expiration date for a domain was removed from your organization.	A domain expiration date is removed because the domain is no longer attributed to your organization.
CHANGE	The expiration date of an apex domain was changed.	A WHOIS domain record for your organization’s apex domain provides a new expiration date for a registered domain. Example: Your organization renews the registration for your marketing site before it expires.

`DOMAIN_REGISTRAR`

These events capture the Registrar of an apex domain attributed to your organization.

Subtype	Description	Real-World Triggers
ADD	A registrar was added to a domain.	The company that the domain was registered with provides a WHOIS domain record for your organization’s apex domain.
REMOVE	The registrar for a domain was removed from your organization.	A registrar removes an event that is only triggered if its domain is removed from your organization.
CHANGE	The registrar for an apex domain was changed.	A WHOIS domain record for your organization’s apex domain showed a new company as the domain’s registrar.

`DOMAIN_MAIL_EXCHANGE_SERVER`

These events relate to mail exchange servers found in MX records in the DNS for an apex domain attributed to your organization.

Subtype	Description	Real-World Triggers
ADD	A mail exchange server was found for a domain.	A DNS MX record for one of your organization’s apex domain listed a mail exchange server.
REMOVE	A mail exchange server was removed from a domain.	The MX record containing your organization’s domain and mail exchange server is no longer found in the DNS. The domain was removed from your organization.

`DOMAIN_NAME_SERVER`

These events relate to name servers found in the DNS for an apex domain attributed to your organization.

Subtype	Description	Real-World Triggers
ADD	A DNS name server was found for a domain.	One of the authoritative DNS name servers for your organization’s apex domain was found.
REMOVE	A name server was removed from a domain.	A name server that used to be authoritative for 1 of your organization’s apex domains was not found to be on subsequent investigation. The apex domain was removed from your organization.

`DOMAIN_HOSTNAME`

These events relate to the inclusion and exclusion of fully qualified domain names in your organization’s attack surface.

Subtype	Description	Real-World Triggers
ADD	A hostname was added for a domain.	A fully-qualified domain name that is a child of 1 of your organization’s apex domains is attributed to your organization.
REMOVE	A hostname was removed for a domain.	A fully-qualified domain name was removed from your organization’s attack surface because there are no longer any connections between this asset and other assets attributed to your organization.

Storage Bucket-related Events

`OBJECT_STORAGE`

Subtype	Description	Real-World Triggers
ADD	A storage bucket was found that may be owned by your organization.	A name that attributed to your organization was found to represent a storage bucket. A cloud connector added a previously unknown storage bucket.
REMOVE	A storage bucket was removed from your organization.	Your organization closed a storage bucket that was previously online.