Run integrations without a Collector

Use this page when you can't run a Collector, for example because your hosts can't reach GitHub (ghcr.io), where the Collector and integration images are published. You download an integration as a file on a machine with internet access, copy it to a Linux host with Docker, and run it there. The data appears in JupiterOne the same way it does with a Collector.

Compared with a Collector, you schedule runs and update integrations yourself.

What you need

• A Linux host with Docker. It must be able to reach:
  • the JupiterOne API: https://api.us.jupiterone.io (EU accounts: https://api.eu.jupiterone.io)
  • the systems you collect from (Active Directory, vCenter, Trellix ePO, ManageEngine)
• A machine with internet access for downloading the integrations, with Docker 28 or later and cosign installed.
• The JupiterOne permission "Update integration".

The examples on this page cover these integrations. Other integrations work the same way; see Other integrations.

Integration	Image name
Microsoft Active Directory	graph-microsoft-active-directory
VMware vSphere	graph-vsphere
Trellix ePO	graph-trellix-epo
ManageEngine Endpoint Central	graph-manage-engine-ec

Step 1. Create the integration in JupiterOne

Do this once for each integration.

1. Go to Integrations, open the integration and select Add integration instance. If you can't find the integration, contact JupiterOne support to enable it for your account.
2. Enter a name.
3. Set Where should this run? to JupiterOne's servers.
4. Set Polling interval to Disabled.
5. Fill in the authentication fields with placeholder text, for example see-host. The real credentials go on your host in Step 4. Skip Test credentials.
6. Select Save.
7. On the Summary tab, copy the Instance ID.
8. On the API Keys tab, select New API Key, then Generate. Copy the key now: it is shown only once and is valid for one year.

caution

Don't select Run for these instances in JupiterOne. The run would fail because JupiterOne's servers can't reach your systems.

Step 2. Download and check the integration

On the machine with internet access. This example uses Active Directory; for another integration, replace graph-microsoft-active-directory with its image name from the table.

1. Download the integration:

   docker pull --platform linux/amd64 ghcr.io/jupiterone/graph-microsoft-active-directory:latest

2. Check that the image you downloaded is signed by JupiterOne:

   IMAGE=$(docker image inspect --format '{{index .RepoDigests 0}}' \
     ghcr.io/jupiterone/graph-microsoft-active-directory:latest)
   COSIGN_REPOSITORY=ghcr.io/jupiterone/graph-microsoft-active-directory-signatures \
     cosign verify "$IMAGE" \
     --certificate-oidc-issuer https://token.actions.githubusercontent.com \
     --certificate-identity-regexp '^https://github\.com/JupiterOne/' > /dev/null && echo verified

   It must print verified.
3. Save it to a file:

   docker save --platform linux/amd64 -o graph-microsoft-active-directory.tar \
     ghcr.io/jupiterone/graph-microsoft-active-directory:latest

4. Copy graph-microsoft-active-directory.tar to your Linux host.

If your Linux host has an ARM processor, use linux/arm64 instead of linux/amd64 in both commands.

Step 3. Load the integration on your host

sudo docker load -i graph-microsoft-active-directory.tar

Step 4. Create a settings file and run each integration

Each integration has its own settings file in /opt/j1. The first four lines are the same for every integration:

• INTEGRATION_INSTANCE_ID and JUPITERONE_API_KEY: the values from Step 1 for that integration.
• JUPITERONE_ACCOUNT: your account ID, under Settings > Account management.
• JUPITERONE_API_BASE_URL: https://api.us.jupiterone.io, or https://api.eu.jupiterone.io for EU accounts.

sudo mkdir -p /opt/j1 && sudo chmod 700 /opt/j1

Microsoft Active Directory

sudo tee /opt/j1/ad.env > /dev/null <<'EOF'
INTEGRATION_INSTANCE_ID=<Instance ID>
JUPITERONE_ACCOUNT=<JupiterOne account ID>
JUPITERONE_API_KEY=<API key>
JUPITERONE_API_BASE_URL=https://api.us.jupiterone.io
LDAP_URL=ldaps://dc1.example.com
BASE_DN=DC=example,DC=com
AD_USERNAME=svc-jupiterone@example.com
AD_PASSWORD=<password>
EOF
sudo chmod 600 /opt/j1/ad.env

sudo docker run --rm --network host --env-file /opt/j1/ad.env \
  ghcr.io/jupiterone/graph-microsoft-active-directory:latest

Is your domain controller's certificate issued by your own certificate authority (CA)? Add the CA to ad.env on one line, writing each line break as \n:

printf '%s\n' "CA_CERTIFICATE=$(awk 'NF {printf "%s\\n", $0}' /path/to/your-ca.pem)" | sudo tee -a /opt/j1/ad.env > /dev/null

VMware vSphere

sudo tee /opt/j1/vsphere.env > /dev/null <<'EOF'
INTEGRATION_INSTANCE_ID=<Instance ID>
JUPITERONE_ACCOUNT=<JupiterOne account ID>
JUPITERONE_API_KEY=<API key>
JUPITERONE_API_BASE_URL=https://api.us.jupiterone.io
DOMAIN=vcenter.example.com
LOGIN=<vCenter user>
PASSWORD=<password>
EOF
sudo chmod 600 /opt/j1/vsphere.env

sudo docker run --rm --network host --env-file /opt/j1/vsphere.env \
  ghcr.io/jupiterone/graph-vsphere:latest

DOMAIN is the vCenter host name only: no https:// and no path. Is the vCenter certificate issued by your own CA? Pass the CA file in the run command:

sudo docker run --rm --network host --env-file /opt/j1/vsphere.env \
  -e CA_CERTIFICATE="$(cat /path/to/your-ca.pem)" \
  ghcr.io/jupiterone/graph-vsphere:latest

Trellix ePO

sudo tee /opt/j1/trellix.env > /dev/null <<'EOF'
INTEGRATION_INSTANCE_ID=<Instance ID>
JUPITERONE_ACCOUNT=<JupiterOne account ID>
JUPITERONE_API_KEY=<API key>
JUPITERONE_API_BASE_URL=https://api.us.jupiterone.io
HOSTNAME=https://epo.example.com:8443
USERNAME=<ePO user>
PASSWORD=<password>
EOF
sudo chmod 600 /opt/j1/trellix.env

sudo docker run --rm --network host --env-file /opt/j1/trellix.env \
  ghcr.io/jupiterone/graph-trellix-epo:latest

HOSTNAME must start with https://. Is the ePO certificate issued by your own CA? Mount the CA file:

sudo docker run --rm --network host --env-file /opt/j1/trellix.env \
  -v /path/to/your-ca.pem:/etc/ssl/your-ca.pem:ro \
  -e NODE_EXTRA_CA_CERTS=/etc/ssl/your-ca.pem \
  ghcr.io/jupiterone/graph-trellix-epo:latest

ManageEngine Endpoint Central (on-premises)

sudo tee /opt/j1/manageengine.env > /dev/null <<'EOF'
INTEGRATION_INSTANCE_ID=<Instance ID>
JUPITERONE_ACCOUNT=<JupiterOne account ID>
JUPITERONE_API_KEY=<API key>
JUPITERONE_API_BASE_URL=https://api.us.jupiterone.io
SELECTED_AUTH_TYPE=onPremLocal
ENDPOINT_CENTRAL_ENDPOINT=https://endpointcentral.example.com:8383
ON_PREM_USERNAME=<user>
ON_PREM_PASSWORD=<password>
EOF
sudo chmod 600 /opt/j1/manageengine.env

sudo docker run --rm --network host --env-file /opt/j1/manageengine.env \
  ghcr.io/jupiterone/graph-manage-engine-ec:latest

To sign in with an Active Directory account, use SELECTED_AUTH_TYPE=onPremAD and add DOMAIN_NAME=<your AD domain>. To use an API token, use SELECTED_AUTH_TYPE=onPremToken and ON_PREM_API_TOKEN=<token> instead of the user name and password.

Is the server's certificate issued by your own CA? Use the same -v and -e NODE_EXTRA_CA_CERTS lines as for Trellix ePO.

Other integrations

Most integrations that run on a Collector can run this way, with the same first four lines. Contact JupiterOne support for the image name and settings of any other integration.

Step 5. Check the result

A run takes from a few seconds to several minutes.

• Success: the output contains Synchronization finalization result., and the instance's Jobs tab in JupiterOne shows Completed.
• Failure: the output contains Synchronization job abort result., and the Jobs tab shows the reason (for example, wrong credentials). Data from earlier runs is kept.

note

The command finishes with exit code 0 even when the run fails. Check the output or the Jobs tab, not the exit code.

Each run fully refreshes the data: records removed from your system are also removed from JupiterOne.

Step 6. Run on a schedule (optional)

This example runs Active Directory every day at 02:00 and keeps the last run's output in /var/log/j1-ad.log. To be alerted when a run fails, have your monitoring check that file for Synchronization finalization result.

For another integration, change ad and the image name. If you added -v or -e lines to the run command, add them to the script too.

sudo tee /opt/j1/run-ad.sh > /dev/null <<'EOF'
#!/bin/sh
docker run --rm --network host --env-file /opt/j1/ad.env \
  ghcr.io/jupiterone/graph-microsoft-active-directory:latest > /var/log/j1-ad.log 2>&1
EOF
sudo chmod 700 /opt/j1/run-ad.sh
echo '0 2 * * * root /opt/j1/run-ad.sh' | sudo tee /etc/cron.d/j1-ad > /dev/null

Don't schedule two runs of the same integration at the same time.

Updating an integration

Repeat Steps 2 and 3. Your settings files and schedules stay the same.

Renewing the API key

The API key expires after one year. Create a new one on the instance's API Keys tab, update JUPITERONE_API_KEY in the settings file, and revoke the old key.

Troubleshooting

You see	What to do
Unable to find image or Docker tries to download	Repeat Step 3. Check that the image name in docker run matches exactly.
UNABLE_TO_VERIFY_LEAF_SIGNATURE	The server's certificate is issued by your own CA. Add it as shown for that integration.
Provider authentication failed	Check the user name, password and server address in the settings file. For vSphere with your own CA, pass the CA with -e CA_CERTIFICATE="$(cat …)", not in the settings file.
401 or Unauthorized from JupiterOne, and the command exits with code 1	Check JUPITERONE_API_KEY and JUPITERONE_ACCOUNT. If needed, create a new key on the instance's API Keys tab.
No job appears in JupiterOne	Check that the host can reach the address in JUPITERONE_API_BASE_URL and that INTEGRATION_INSTANCE_ID is correct.