Logbook Event Catalog (Reference)
Understanding the Logbook
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.
This section discusses the real-world scenarios that trigger logbook events and lists related events.
Logbook Event Categories
All logbook events fall into three categories
Example Scenario Illustrating Relationships Between Events
If a host is attributed to your organization, and that host has one 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 five event types (and subtypes) would appear in this order in the logbook:
-
Host (Associate)
-
Port (Add)
-
Protocol (Add)
-
Software (Add)
-
Vulnerability (Add)
If that same host were removed from your organization, the domino effect would result in five more event types (and subtypes) in the logbook:
-
Vulnerability (Remove)
-
Software (Remove)
-
Protocol (Remove)
-
Port (Remove)
-
Host (Disassociate)
Host-Related Events
Censys hosts are IP addresses. Hosts have many characteristics and properties which indicate the services in use by your organization.
HOST
Events of this type are related to the inclusion or exclusion of IP addresses in your organization’s attack surface.
Subtype ASSOCIATE
Description
An IP address was added to your organization’s asset collection.
Real-World Triggers
-
An IP that did not have any 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 that has had 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.
Subtype DISASSOCIATE
Description
An IP address was removed from your organization’s asset collection.
Real-World Triggers
-
An IP that is associated to you is found to have 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 in order to mute the noise.
Cascading Event Types That Could Follow a Host Event
Subtype would match the Host event, (e.g. Host Associate would be followed by Add events, and Host Disassociate would be followed by Remove events).
HOST_PORT
Events of this type relate to the ports on a host attributed to your organization.
Subtype ADD
Description
A new port was added to an IP.
Real-World Triggers
-
An IP attributed to your organization was found to have a port open that was not open in the most recent Censys scan.
Example: Your organization exposed a new service to the Internet on a port.
Subtype REMOVE
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.
Cascading Event Types That Could Follow a Port Event
Subtype would match the Port event.
HOST_PROTOCOL
Events of this type are related to the application-layer protocol(s) or protocol category detected on an open port.
Subtype ADD
Description
A protocol or protocol category was added to an IP.
Real-World Triggers
-
A new application-layer protocol is detected by Censys scanners on one or more ports of an IP attributed to your organization.
Example: A web server communicates using HTTP on a port.
Subtype REMOVE
Description
A previously seen protocol or protocol category was removed from an IP.
Real-World Triggers
-
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 Could Follow a Protocol Event
Subtype would match the Protocol event.
HOST_SOFTWARE
Events of this type relate to the software packages and versions reported by a service during a Censys scan of an IP.
Subtype ADD
Description
A software package was added to an IP.
Real-World Triggers
-
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.""
Subtype REMOVE
Description
A software package was removed from an IP.
Real-World Triggers
-
A software package that was reported by one 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.
Cascading Event Types That Could Follow a Software Event
HOST_VULNERABILITY
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.
Subtype ADD
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 one 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 one 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.
Subtype REMOVE
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 one 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.
Subtype CHANGE
Description
The information about a vulnerability was changed.
Real-World Triggers
-
A CVE-ID in the Common Vulnerabilities and Exposures (CVE) database that applies to software running on your one of your organization’s host was updated
Example: The description, severity score, or list of affected software configurations was updated for a CVE-ID.
HOST_CERT
Events of this type record the presentation of your organization’s certificates by your hosts during a TLS handshake with a Censys scanner.
Subtype ADD
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.
Subtype REMOVE
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 one of your web services with a new one.
Certificate-Related Events
TLS certificates on hosts are used for verifying the identity claim of a server.
CERTIFICATE
Events of this type are related to the inclusion or exclusion of TLS certificates in your organization’s attack surface.
Subtype ASSOCIATE
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.
Subtype 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 Could Follow a Certificate Event
Domain-Related Events
Apex domains are root domains in the sense that they are only subdomains of a TLD (e.g., com) or eTLD (e.g., co.uk).
These domains often identify large portions of your Internet-facing business.
DOMAIN
Events of this type record the inclusion or exclusion of apex domains in your organization’s attack surface.
Subtype ADD
Description
An apex domain was added to your organization.
Real-World Triggers
-
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.
Subtype REMOVE
Description
An apex domain was removed from your organization.
Real-World Triggers
-
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
DOMAIN_EXPIRATION_DATE
Events of this type capture the expiration date of an apex domain attributed to your organization.
Subtype ADD
Description
An expiration date was found for a domain.
Real-World Triggers
-
A WHOIS domain record for your organization’s apex domain provided the expiration date of the registration.
Subtype REMOVE
Description
An expiration date for a domain was removed from your organization.
Real-World Triggers
-
A domain expiration date is removed because the domain is no longer attributed to your organization.
Subtype CHANGE
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.
DOMAIN_REGISTRAR
Events of this type capture the Registrar of an apex domain attributed to your organization.
Subtype ADD
Description
A registrar was added to a domain.
Real-World Triggers
-
A WHOIS domain record for your organization’s apex domain provided the company that the domain was registered with.
Subtype REMOVE
Description
The registrar for a domain was removed from your organization.
Real-World Triggers
A registrar remove event is only triggered if its domain is removed from your organization.
Subtype CHANGE
Description
The registrar for an apex domain was changed.
Real-World Triggers
-
A WHOIS domain record for your organization’s apex domain showed a new company as the domain’s registrar.
DOMAIN_MAIL_EXCHANGE_SERVER
Events of this type relate to mail exchange servers found in MX records in the DNS for an apex domain attributed to your organization.
Subtype ADD
Description
A mail exchange server was found for a domain.
Real-World Triggers
-
A DNS MX record for one of your organization’s apex domain listed a mail exchange server.
Subtype REMOVE
Description
A mail exchange server was removed from a domain.
Real-World Triggers
-
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
Events of this type relate to name servers found in the DNS for an apex domain attributed to your organization.
Subtype ADD
Description
A DNS name server was found for a domain.
Real-World Triggers
-
One of the authoritative DNS name servers for your organization’s apex domain was found.
Subtype REMOVE
Description
A name server was removed from a domain.
Real-World Triggers
-
A name server that used to be authoritative for one of your organization’s apex domains was not found to be on subsequent investigation.
-
The apex domain was removed from your organization.
DOMAIN_HOSTNAME
Events of this type relate to the inclusion and exclusion of fully qualified domain names in your organization’s attack surface.
Subtype ADD
Description
A hostname was added for a domain.
Real-World Triggers
-
A fully-qualified domain name that is a child of one of your organization’s apex domains is attributed to your organization.
Subtype REMOVE
Description
A hostname was removed for a domain.
Real-World Triggers
-
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 ADD
Description
A storage bucket was found that may be owned by your organization.
Real-World Triggers
-
A name that attributed to your organization was found representing a storage bucket.
-
A cloud connector added a previously unknown storage bucket.
Subtype REMOVE
Description
A storage bucket was removed from your organization.
Real-World Triggers
-
Your organization closed a storage bucket that was previously online.
Accessing the Logbook
Logbook events can be viewed in the Censys Platform app and are available for query via REST API.
To tour the Logbook page in the app, read this guide.
Logbook API
The Censys Logbook REST API allows Censys Platform customers to poll the logbook for changes in their attack surface that meet their interests.
To filter events in the logbook, you must create an initial cursor. You will use the cursor to submit a GET request to the logbook endpoint, which will return a new cursor as part of the response payload to use in the next request.
Visit our API documentation for details on methods.
Comments
0 comments
Article is closed for comments.