Censys has deep roots in open source software, originating from the open source project, Zmap. Since then, Censys has continued to support open source projects and contribute to our public repositories which can be found here.
One of our most popular open source projects is our censys-python library. The library was originally created for Censys Search and is an easy-to-use and lightweight API wrapper, currently used in 180 projects across GitHub. With the recent release (v1.1.0), this library now includes a second API for the Attack Surface Management Platform (or ASM Platform). The Censys ASM API enables users to programmatically interact with resources on our ASM platform, including seeds, assets, and logbook events.
- seeds – Provides programmatic management of seeds in the ASM platform.
- assets – Returns asset data for hosts, certificates, and domains. This option also allows the user to manage tags and comments on assets.
- events – Returns logbook events. Can be used to execute targeted searches for events based on start id or date, and event type filters.
As a customer of the ASM Platform, this update allows users to automate their interactions in just a few short commands such as adding new seed data to the platform and fetching associated assets like IP addresses and domain names. Users can even keep track of their ASM asset history using the logbook endpoints and its event objects.
For example, adding new seeds to the Censys ASM Platform is now even easier:
| from censys.asm.seeds import Seeds
s = Seeds()
# Add a list of seeds. To add a single seed, just pass a list containing one seed.
# Here, we add two ASN seeds.
seed_list = [
{“type”: “ASN”, “value”: 99998, “label”: “seed-test-label”},
{“type”: “ASN”, “value”: 99999, “label”: “seed-test-label”}
]
s.add_seeds(seed_list)
# Add a list of seeds, replacing existing seeds with a specified label
# Here, all seeds with label=”seed-test-label” will be removed and then
# Seeds 99996 and 99997 will be added.
seed_list = [
{“type”: “ASN”, “value”: 99996},
{“type”: “ASN”, “value”: 99997}
]
s.replace_seeds_by_label(“seed-test-label”, seed_list) |
As for assets, there are three types (hosts, certificates, and domains), each sharing the same API interface. An example of how you might go about viewing your assets on the Censys ASM Platform is:
| from censys.asm.assets import Assets
h = Assets(“hosts”)
# Get a generator that returns hosts
hosts = h.get_assets()
print(next(hosts))
# Get a single host by ID (here we get host with ID=”0.0.0.0″)
host = h.get_asset_by_id(“0.0.0.0”)
print(host) |
Events are changes in the user’s attack surface such as a user adds a new certificate, a user opens a new port, etc.. Here is an example of how quickly you can grab your logbook, or list of all these type of events in chronological order, from the ASM platform:
| from censys.asm.events import Events
e = Events()
# Get a generator that returns all events
events = e.get_events()
print(next(events))
# Get events based off cursor specifications
events = e.get_events(cursor)
print(next(events)) |
If you have any issues or want to contribute to the library, please submit your pull request and we’ll get back to you with any questions! For more information about the ASM API and how to leverage the API in your current workflows, please see our documentation.
