Getting Started#
It is important to note that this connector is a Python package. This allows you to run the connector from the command line as well as enables you to run the connector in as many different environments as you wish. We have provided a variety of deployment types and configuration options. We recommend that you install the package locally to take advantage of the configuration command line interface (censys-cc). After you have configured the connector, you can deploy it to your environment.
Prerequisites#
Note
There may be additional requirements depending on the deployment method
Installation#
Clone the repo
git clone https://github.com/censys/censys-cloud-connector.git
cd censys-cloud-connector
Ensure you have poetry installed (may require restarting shell)
pip install --upgrade poetry
Start a shell and activate the virtual environment (this is optional if you’d like to install dependencies globally)
poetry shell
Install the dependencies (a Makefile is provided for convenience in installation)
make install-all # Install dependencies for all providers
make install-azure # Azure only
make install-aws # AWS only
make install-gcp # GCP only
Copy .env.sample to .env
cp .env.sample .env
Environment Variables#
The connector uses environment variables to configure the connector. The
CENSYS_API_KEY
environment variable is required to run the connector.
The following environment variables are available for use in the connector:
- CENSYS_API_KEY#
Your Censys ASM API key found in the ASM Integrations Page. (Required)
- PROVIDERS_CONFIG_FILE#
The path to Provider Configuration.
Default:
./providers.yml
- SECRETS_DIR#
The path to the directory containing the secrets.
Default:
./secrets
- LOGGING_LEVEL#
The logging level. Valid values are
DEBUG
,INFO
,WARN
,ERROR
, andCRITICAL
.Default:
INFO
- DRY_RUN#
If set to
true
, the connector will not write any data to the ASM platform.Default:
false
- HEALTHCHECK_ENABLED#
If set to
false
, the connector will not report its health to the ASM platform.Default:
true
- AZURE_REFRESH_ALL_REGIONS#
Azure-specific environmental variable. If set to
true
, the connector will clear stale seeds from regions no longer containing assets. This may take longer to run, but will ensure that stale seeds do not persist in the workspace. If set tofalse
, the connector will submit seeds that are found as normal.Default:
false
Sample .env
File#
.env.sample
is a sample file that contains the above environment variables.
Please use this file as a template to create your own .env
file.
CENSYS_API_KEY=your-censys-api-key-here-xxxxxxxxxxx
SECRETS_DIR=./secrets
PROVIDERS_CONFIG_FILE=./providers.yml
LOGGING_LEVEL=INFO
DRY_RUN=false
HEALTHCHECK_ENABLED=true
AZURE_REFRESH_ALL_REGIONS=false
# Censys API Settings
# CENSYS_ASM_API_BASE_URL=https://app.censys.io/api
# CENSYS_COOKIES={"key": "value"}