Install pcap Sensor
Prerequisites
- Docker Engine version
18.03.0
and above - Admin (or
sudo
) privileges on the Docker host - AWS profile access key and secret access key saved at path ~/.aws/credentials file
- The profile should have all the required permissions as listed here
- Refer pcap-filter-guide to apply filters.
NOTE: You need to have the satellite installed already to configure the sensor to point to it. If you haven't done it already, head over to Install Satellite
Follow instructions for your platform
Install Sensor on Fargate
The pcap Sensor can be installed as a sidecar on an existing AWS task by adding to its task definition via the AWS Console.
The steps to add the sensor to your task are as follows
- Go to Task Definitions
- Select the required task definition
- Click on
Create revision with JSON
- Add the given JSON object under ContainerDefinitions
- Replace the values for satellite-url, levo-env and levoai-org-id in entrypoint.
- Replace the values for Environment and LogConfiguration as per your requirement.
- Set the memory limit in
Mib
(Note: memory should not exceed the Task memory limit)
{
"name": "levo-pcap-sensor",
"image": "levoai/pcap-sensor",
"cpu": 0,
"memory": 2048,
"portMappings": [],
"essential": false,
"entryPoint": [
"./bin/levo-pcap-sensor",
"apidump",
"--satellite-url",
"< INSERT SATELLITE URL (http(s)://hostname|IP:port) >",
"--levo-env",
"<INSERT APPLICATION ENVIRONMENT (staging, production etc.)>",
"--levoai-org-id",
"< INSERT LEVO ORG ID >"
],
"environment": [
{
"name": "LEVO_AWS_REGION",
"value": "< INSERT AWS REGION (us-west-2) >"
}
],
"mountPoints": [],
"volumesFrom": [],
"logConfiguration": {
"logDriver": "awslogs",
"options": {
"awslogs-group": "< INSERT LOGS IDENTIFIER (/ecs/your-application-pcap) >",
"awslogs-create-group": "true",
"awslogs-region": "< INSERT AWS REGION (us-west-2) >",
"awslogs-stream-prefix": "ecs-pcap"
}
}
}
Specify additional flags in the entrypoint
--trace-export-interval # default 10s
--rate-limit # default 1000/min
--filter # eg. port 8080 and (not port 8081)
--host-allow # regex for allowed hosts
--path-allow # regex for allowed paths
--host-exclusions # regex for excluded hosts
--path-exclusions # regex for excluded paths
Install via Docker
Prerequisites
- Docker Engine version
18.03.0
and above - Admin (or
sudo
) privileges on the Docker host
If you are running the satellite as a docker container on the host machine, use the satellite-url http://host.docker.internal:9999
Do NOT use localhost
as the hostname, since the sensor is running inside a container.
sudo docker run --net=host --rm -it levoai/pcap-sensor \
./bin/levo-pcap-sensor apidump \
--satellite-url "your satellite url (http(s)://hostname|IP:port)" \
--levo-env "your application environment (staging, production etc.)" \
--levoai-org-id "your levo org id"
Specify additional flags in the command
--trace-export-interval "trace export interval in seconds (default 10)"
--rate-limit "rate limit in traces per min (default 1000)"
--filter "pcap filter string, eg. port 8080 and (not port 8081)"
--host-allow "host allow regex"
--path-allow "path allow regex"
--host-exclusions "host exclude regex"
--path-exclusions "path exclude regex"
Install on Kubernetes as daemonset
Prerequisites
- Kubernetes version >= v1.18.0
- Helm v3 installed and working.
- The Kubernetes cluster API endpoint should be reachable from the machine you are running Helm.
kubectl
access to the cluster, withcluster-admin
permissions.
1. Install levoai helm repo
helm repo add levoai https://charts.levo.ai && helm repo update
2. Create levoai namespace and install pcap-sensor
# Replace 'hostname|IP' & 'port' with the values you noted down from the Satellite install
# If Sensor is installed on same cluster as Satellite, use 'http://levoai-satellite:9999'
# Specify below the 'Application Name' chosen earlier.
#
helm upgrade levoai-pcap-sensor levoai/levoai-pcap-sensor \
--install \
--namespace levoai \
--create-namespace \
--set sensor.config.levoaiOrgId="your Levo Org ID" \
--set sensor.config.satelliteUrl="http(s)://hostname|IP:port"
--set sensor.confg.levoEnv="your application environment (staging, production etc.)"
Set additional configs
sensor.config.traceExportInterval="trace export interval in seconds (default 10)"
sensor.config.rateLimit="rate limit number in traces/min (default 1000)"
sensor.config.fitler="pcap filter string, eg. port 8080 and (not port 8081)"
sensor.config.hostAllow="host allow regex"
sensor.config.pathAllow="path allow regex"
sensor.config.hostExclusions="host exclusion regex"
sensor.config.pathExclusions="path exclusion regex"
AWS Permissions needed
Add the AmazonECS_FullAccess policy to get access to all the necessary permissions.
Action | Resource | Purpose |
---|---|---|
ec2:DescribeRegions | * | Find the list of AWS regions you have enabled. (If not present, defaults to a precompiled list.) |
ecs:ListClusters | * | Find the available ECS clusters. |
ecs:DescribeClusters | , or restricted to account like arn:aws:ecs:::cluster/* | Look up the names of the available ECS clusters. |
ecs:ListTaskDefinitionFamilies | * | Find the available task definitions. |
ecs:DescribeTaskDefinition | * | Read the existing task definition in order to copy it. |
ecs:RegisterTaskDefinition | * | Write a new version of the task definition. |
ecs:ListServices | * | Find the available services. |
ecs:DescribeServices | *, or restricted to your account, or restricted to the cluster you selected | Identify which services are using the task definition you selected. |
ecs:UpdateService | *, or restricted to your account, or restricted to the cluster you selected | Update and restart the service using the new task definition. |
ecs:TagResource | *, or restricted to your account, or restricted to the cluster you selected | Mark the service as having been updated by Levoai. |