Censys Platform for Splunk

This app implements investigative actions to get information from the public Censys Platform API into Splunk SOAR.

Getting Started

Prerequisites

1. You are using a Mac or Linux machine (the Splunk SDK does not support Windows)
2. git is available in your CLI

Installation

1. Install uv, which is our Python dependency/environment manager
2. Using uv, install Python 3.14 (uv python list → uv python install [version_you_choose])
3. Install the splunk-soar-sdk as a uv tool: uv tool install splunk-soar-sdk
4. Install the linting/pre-commit tools: uv tool install ruff and uv tool install pre-commit --with pre-commit-uv
5. Install the project's dependencies: uv sync

Configuration

It is recommended that, when developing, you use the Python environment managed by uv. You can do this by running source ./.venv/bin/activate in the base directory of this repository once the installation steps above are complete.

Add-on settings are managed through the SDK's Asset Configuration definitions. The configuration exposed by the add-on includes:

• api_token: This is how you'll specify your PAT (personal access token) for authentication purposes
• organization_id: This is your organization ID within the Censys Platform which is used alongside your PAT to authenticate a request
• base_url (optional): This is used to define the base URL (protocol and domain) through which the Censys Platform API should be accessed

To specify these config values, create a test_asset.json file in the base directory of this repository, then populate the fields as appropriate.

Testing Locally

Testing is facilitated by using the splunk-soar-sdk tool, installed above. We recommend following the SDK instructions for running actions via the CLI as the primary development workflow, using a SOAR Cloud/on-prem instance just as a final verification step.

Parameters to the actions are passed via a JSON params file. You can create a test_params.json file in the base directory of this repository and it will be excluded from source control. You can create multiple param files (such as for each action) by following the pattern test_params_{name}.json.

To run a particular action via the CLI, invoke the add-on via Python directly:

python -m src.app action lookup_host -p test_param_host_.json -a test_asset.json

Actions

These are the available base commands. To run one successfully, you will still need an appropriate asset file (specified with -a) and param file (specified with -p) as mentioned above.

Action	CLI Command	Description	Docs
lookup_host	python -m src.app action lookup_host	Retrieves a host by IP lookup	Host Definitions
lookup_cert	python -m src.app action lookup_cert	Retrieves a certificate by SHA256 lookup	Cert Definitions
lookup_web_property	python -m src.app action lookup_web_property	Retrieves a web property by hostname:port lookup	Web Property Definitions
search	python -m src.app action search	Performs a search across all Censys assets using the given query	Search Result Docs
test_connectivity	python -m src.app action test_connectivity	Tests whether the asset file is sufficient to connect to the API	N/A

To add a new action, create a new file in actions with the same name as the search. Once it is ready to be tested, update actions/registration.py to register the new action, providing useful short/long descriptions. Lastly, update the above table to include the new action.

Helpful Resources

• Censys Data Definitions
• Censys Platform API Docs
• Censys Platform Python SDK
• Splunk SDK Docs
• uv docs

License