How to use astra-cli for Astra Proxy Service

Astra-cli is a wrapper tool around docker to manage astra-proxy-service on the fly. It can be used to setup and manage the astra-proxy-service by launching this proxy service as a container. This guide will cover how to use astra-cli to manage astra-proxy-service. It also covers troubleshooting common issues encountered for astra-proxy-service.

astra-proxy-service makes use of well known mitmproxy as upstream proxy server. This service by default doesn't verify the upstream certificates and hence the certificate verification is left to the application

Download astra-cli from repository

Refer here to get started with astra-cli integration

Manage astra-proxy-service by using astra-cli

Environment file is mandatory for the astra-proxy-service to start

Create an env file called as proxyEnv.env and add SENSOR_ID, ALLOWED_HOSTS, OTEL_EXPORTER_ENDPOINT entries to this env file where:

SENSOR_ID is the integrationID displayed in the integrations page of getastra
ALLOWED_HOSTS is the comma separated list of FQDNs. Minimum one, maximum five comma separated FQDNs can be given.
OTEL_EXPORTER_ENDPOINT is the address of the astra-traffic-collector

Example env file is shown below

SENSOR_ID=f0dd7367-5f66-4c1b-bd73-74da8a5b78a6
ALLOWED_HOSTS=mydomain.dev, mydomain.com, testing.com
OTEL_EXPORTER_ENDPOINT=localhost:4317

Start the astra-proxy-service container under quickstart mode

quickstart mode accepts two parameters, --listen-port and --env-file where:

--listen-port : will set the port on which http proxy should be listening to
--env-file : will set the env file to read from

Following command will start a simple http proxy server by binding the astra-proxy-service to host network. Proxy will be accessible at address http://localhost:8181

./astra-cli proxy quickstart --listen-port 8181 --env-file proxyEnv

Start the astra-proxy-service with additional flags

astra-cli being a wrapper around docker, the cli supports almost all the flags supported by docker run. Additionally, the astra-proxy-service makes use of well known mitm proxy, and hence supports all the flags supported by mitmdump

Following is a sample command which will start astra-proxy-service with docker container port mapping.

./astra-cli proxy start --env-file .env --rm -p 8080:8181

Check the status of astra-proxy-service

./astra-cli proxy status

You should see similar output like this

CONTAINER ID   IMAGE            COMMAND                  CREATED          STATUS          PORTS                                                 NAMES
4e0090bb1ae9   getastra/proxy   "mitmdump -k -s /app…"   35 minutes ago   Up 35 minutes   8080/tcp, 0.0.0.0:8080->8181/tcp, :::8080->8181/tcp   astra-proxy-service

Check the logs of astra-proxy-service

./astra-cli proxy logs

To tail the logs:

./astra-cli proxy logs --tail=0 -f

To check the logs for last 5 minutes

./astra-cli proxy logs --since=5m

To stop astra-proxy-service

./astra-cli proxy stop

To stop astra-proxy-service

./astra-cli proxy remove

Upgrade

Docker container upgrade

This process updates the docker container to a new version of the astra-proxy-service.

Change directory to the place where astra-cli executable is downloaded

Run below command

./astra-cli proxy upgrade

Upon successfull image pull, run this to stop the current container and subsequently remove it

./astra-cli proxy stop
./astra-cli proxy remove

Restart the container with newly pulled image

./astra-cli proxy quickstart --listen-port 8181 --env-file proxyEnv

Troubleshooting

traces are not captured by astra-proxy-service

Symptoms

I have configured the astra-proxy-service upstream proxy address in my Postman/Burp/Curl. I don't see any API endpoint entry in my inventory when I run my postman collection.

Cause

Potential problem with env file

astra-traffic-collector is unable to forward the traces to Astra. Refer here

Solution

Ensure right SENSOR_ID, ALLOWED_HOSTS and OTEL_EXPORTER_ENDPOINT are set in env file.

Double check if the hostname is registered under Scope URI for Report in Target setup page

Updated on: 03/01/2025