Aikido Broker for Internal Applications

Use the Aikido Broker to scan and monitor applications that live on internal networks and are not reachable from the internet.

The broker runs inside your infrastructure and forwards Aikido’s requests to the internal URLs you allow.

When to use the Broker

Use the broker with any Aikido scan on applications or services that only exists inside your company network, including:

• Code scanning on on-prem GitLab or other local code platforms

• Container scanning on private or on-prem container registries

• AI pentesting on internal applications

• Front-end and API testing scans on internal domains or services

Requirements

To run the Aikido Broker you need:

• Docker and Docker compose installed

  • Optionally Kubernetes 1.19+

• Network access to the internal applications you want Aikido to scan

• Outbound HTTPS access to *.aikidobroker.com

• Enough CPU (1 core) and memory (1 GB) to run a small container

Installation

1

Generate and set a broker client token

Go to Broker Clients page and create a new broker client secret. Save the Client Secret for next step.

If you're unable to access this page, reach out to support in the Aikido dashboard

2

Add resources (internal URL's)

Define which internal URLs Aikido is allowed to access through the broker.

These are the applications and APIs you want Aikido to scan, for example:

• https://api.internal.corp.local

• http://service-a.internal:8080

• https://10.0.5.20

You can manage these resources in the Aikido UI or in your broker configuration, depending on how your setup is structured.

3

Start the broker

Bring up the broker service on a machine with access to the internal applications you want Aikido to access. Make sure to replace the CLIENT_SECRET value with the one generated on clients page.

Docker

docker run -d \
  --name aikido-broker \
  --restart=on-failure:3 \
  --network host \
  -e CLIENT_SECRET="AIK_BROKER_XXX_YYY_ZZZZ" \
  -e ALLOWED_INTERNAL_SUBNETS="192.168.0.0/16,10.0.0.0/8,172.16.0.0/12,127.0.0.0/8" \
  aikidosecurity/broker-client:latest

You can check if the Broker is running expected with docker logs aikido-broker

Kubernetes

4

Wait for broker to stabilize

Give it about 30 seconds to connect to Aikido and register.

Once it is up and connected, Aikido can start reaching the internal resources you configured.

Configuration

You can control how the broker reaches your internal services and how it resolves hostnames.

ALLOWED_INTERNAL_SUBNETS

List of CIDR ranges that the broker is allowed to call.

Use this to:

• Limit the broker to specific internal networks

• Prevent accidental access to unrelated infrastructure

Example:

ALLOWED_INTERNAL_SUBNETS=10.0.0.0/8,192.168.1.0/24

DNS_SERVERS

Optional list of DNS servers the broker should use to resolve internal hostnames.

Use this if:

• You have internal DNS zones (for example *.corp.local)

• Your internal services are not resolvable with public DNS

Example:

DNS_SERVERS=10.0.0.10,10.0.0.11

NODE_EXTRA_CA_CERTS for Custom CA (internal TLS)

If your internal services use certificates signed by a private CA, provide that CA so the broker can validate TLS correctly.

Typical use cases:

• Internal services with self-signed certificates

• Internal PKI for service-to-service encryption

How you configure this depends on your deployment, but at a high level you will:

• Mount your custom CA file into the broker container

• Point the broker to that CA file using the provided environment variable or config option

When you add custom certificates the broker must be able to read them inside the container. Mount the certificate folder into the container with an extra -v flag and point the broker to the certificate file with the NODE_EXTRA_CA_CERTS variable. Here is a short example:

docker run -d \
  --name aikido-broker \
  --restart=on-failure:3 \
  --network host \
  -v /path/to/corporate-ca.crt:/certs/corporate-ca.crt:ro \
  -e CLIENT_SECRET="{secret}" \
  -e ALLOWED_INTERNAL_SUBNETS="192.168.0.0/16,10.0.0.0/8,172.16.0.0/12,127.0.0.0/8" \
  -e NODE_EXTRA_CA_CERTS=/certs/corporate-ca.crt \
  aikidosecurity/broker-client:latest

Proxy

If your internal network requires a proxy to reach certain hosts or the internet, configure the broker to use that proxy.

This is useful when:

• Outbound traffic in your network must go through an HTTP or HTTPS proxy

• Internal segments are only reachable via a central proxy

Configure the proxy URL through the broker’s proxy setting or environment variables: HTTP_PROXY, HTTPS_PROXY, ALL_PROXY

How to use Broker resources with Aikido

After you install the broker and add your internal URLs as resources, the broker generates a unique Aikido URL for each resource. These URLs act as secure entry points for Aikido to reach your internal services through the broker.

Use these Aikido Broker URLs in all Aikido scans.

This is important because:

• Aikido cannot reach your internal network directly

• The broker maps the Aikido URL to your internal service

• Using the internal URL directly will not work

Example

When configuring a Domains and API scan (front-end scan), use the Broker URL instead of the internal address.

For example:

• Do not use http://my-internal-app.test:8000

• Use the generated broker URL, such as: https://4948_c562ddc641.aikidobroker.com

Troubleshooting

Check logs

Check the Docker logs for warning messages and errors:

Docker

docker logs aikido-broker

Kubernetes

Error: Cannot access another client's resources

The cached client id no longer matches the CLIENT_SECRET organization. Delete the config/client_id file and try again.