After adding Trace Sources to the Panoptica console, you will need to install Panoptica's trace source scanner in your API Gateway. The method or doing so varies according to the Trace Source type you select. Click the three dots (•••) to the right of each Trace Source added, and select Download Installation Instructions. The installation bundle for each Trace Source contains executable code, as well as instructions in a README.md file.

Here you will find detailed instructions for attaching each type of Trace Source. Click the Trace Source you're installing to expand the instructions below:

F5 BIG-IP

F5 BIG-IP

Follow the steps below to configure a F5 BIG-IP Local Traffic Manager (LTM) plugin to capture Trace Sources for Panoptica's API Security controller .

For more information about F5 BIG-IP LTM please visit: https://www.f5.com/products/big-ip-services/local-traffic-manager

Prerequisites

F5 BIG-IP is running in your Kubernetes cluster.
Panoptica API Security controller is installed in the same cluster, and exposed externally through a publicly reachable URL. See Exposing the API Controller for Trace Sources for details.
Another host (e.g. Virtual Machine), able to run a docker container that will collect and forward the traces. This host (F5-Log-Collector) must be reachable by F5 BIG-IP, and able to reach the Panoptica API Security controller.

Environment variables

Replace the environment variables below with the appropriate values:

APISEC_URL: URL where API Security Controller is deployed
Example: https://1.2.3.4:443/apisec
APISEC_CERT_HOSTNAME: Host where the API Security certificate is located.
Example: 1.2.3.4
APISEC_CERT_PATH: Path to the API Security certificate generated for the F5 BIG-IP instance
Example: /path/to/apisec.crt

Install Instructions

Prepare the bundle

Generate the installation bundle by running the following script, substituting the environment variables detailed above:

   ```
   APISEC_URL=<url> \
   APISEC_CERT_HOSTNAME=<host> \
   APISEC_CERT_PATH=<path> \
   ./preparebundle.sh
   ```

The generated bundle will be named F5BigIPBundle, and contains all the files needed for subsequent steps.

Configure High Speed Logging in BIG-IP
1. Connect to BIG-IP management console
2. In System->Configuration->Log Destinations click on the + button
3. Fill in the form as follows:
  - Name: ApiSecAgent
  - Description: APISec Agent receiving hsl
  - Type: Management Port
  - Address: [The host where F5-Log-Collector is reachable from BIG-IP]
  - Port: 10514
  - Protocol: udp
4. In System->Configuration->Log Publishers click on the + button
5. Fill in the form as follows:
  - Name: APISecLogPublisher
  - Description: ApiSec Log Publisher
  - Destinations: Make sure ApiSecAgent is in the list of selected destinations
Configure Log Publisher iRule in BIG-IP
1. Connect to BIG-IP management console
2. In Local Traffic->iRules->iRule List click on the + button
3. Fill in the form as follows:
  - Name: APISecLogPublisher
  - Definition: From the bundle folder, copy the content of F5BigIPBundle\iRule\APISecLogPublisher.tcl
Deploy APISec Agent on the F5-Log-Collector
1. From the bundle, copy the folder F5BigIPBundle/ApiSecAgent to F5-Log-Collector host
2. Connect to F5-Log-Collector host
3. Build the API Security Agent container image:
  - Go in the folder ApiSecAgent
  - Execute:
```
dockerbuild.sh
```
4. Launch the API Security Agent:
  - Go to the folder ApiSecAgent/deploy/docker
  - Execute:
```
launch.sh
```

Kong

Kong

Configuring Panoptica to capture Trace Sources in a Kong gateway is a two-step process. First you install our Kong plugin, then you configure the tracing. For more information, see Getting Started With The Kong Ingress Controller

Prerequisites

Kong is running in your Kubernetes cluster
Panoptica API Security controller is installed in the same cluster

Environment variables

Replace the environment variables below with the appropriate values:

KONG_GATEWAY_DEPLOYMENT_NAMESPACE: Namespace where Kong is deployed
Default: kong
KONG_GATEWAY_DEPLOYMENT_NAME: Deployment name of Kong
Default: kong
KONG_PROXY_CONTAINER_NAME: Name of the Kong container inside the Kong deployment.
Default: proxy

Install

To add the Panoptica Trace Source plugin to your Kong deployment and Ingress configuration, run the following commands:

KONG_GATEWAY_DEPLOYMENT_NAMESPACE=<namespace> \
KONG_GATEWAY_DEPLOYMENT_NAME=<name> \
KONG_PROXY_CONTAINER_NAME=<name> \
./kong_plugin.sh deploy

To troubleshoot the plugin, add the following to the above commands:

LOG_LEVEL=debug

Uninstall

To remove the plugin from your Kong deployment, run the following command:

KONG_GATEWAY_DEPLOYMENT_NAMESPACE=<namespace> \
KONG_GATEWAY_DEPLOYMENT_NAME=<name> \
KONG_PROXY_CONTAINER_NAME=<name> \
./kong_plugin.sh undeploy

Enable tracing

After installing the plugin in the Kong gateway, you need to create an annotation to enable the tracing. You can choose whether to enable the tracing on an ingress, or on specific services , by annotating the corresponding resource.

Ingress

To configure tracing on an ingress, run this command.

kubectl --namespace <your namespace> annotate ingress <your ingress name> "konghq.com/plugins=api-traces-plugin"

For additional details, see Using plugins on Ingress / Gateway API Routes

Services

To configure tracing on a specific service, run this command:

kubectl --namespace <your namespace> annotate service <your service name>  "konghq.com/plugins=api-traces-plugin"

For additional details, see Using plugins on Services.

Preserving Client IP Address

Kong is usually deployed behind a Load Balancer, using a Kubernetes LoadBalancer service. This can result in a loss of actual Client IP address, as Kong will receive the IP address of the Load Balancer rather than that of the client.
See Preserving Client IP Address in the Kong guides for various methods for solving this problem.

Apigee X

Apigee X

Install this plugin to integrate your Apigee X platform with Panoptica. You can choose either the
For more information about Apigee X please visit: https://cloud.google.com/apigee/docs

Prerequisites

Panoptica API Security controller is running, and exposed externally through a publicly reachable URL. See Exposing the API Controller for Trace Sources for details.
There is an Apigee X proxy configured in your GCP account, with connectivity to the Panoptica API Security controller.

Automated installation

Prerequisites for automated installation

apigeecli - to interact with Apigee APIs
wget or curl
jq - command-line JSON processor
gcloud - command line interface

Usage

Download the Apigee X bundle from the Panoptica console, and

Install Instructions

Download the Istio bundle and execute the script to create the pod
```
./deploy.sh
```

Create a label for the application namespace that will be sending the traces

kubectl label namespace <name of the application namespace> SecureApplication-protected=full

Uninstall Instructions

Remove the label that was created during installation

kubectl label namespace <name of the application namespace> SecureApplication-protected-

Execute the script to delete the pod
```
./undeploy.sh
```

Istio

Istio

Configuring Panoptica to capture Trace Sources from Istio is a simple matter of deploying a pod in the Panoptica namespace running in your cluster.

For more information about Istio plugins, see: https://istio.io/latest/docs/reference/config/proxy_extensions/wasm-plugin/

Prerequisites

Istio is installed in the cluster, and Istio injection is enabled
Panoptica API Security controller is installed in the same cluster

Install Instructions

Download the Istio bundle and execute the script to create the pod
```
./deploy.sh
```

Create a label for the application namespace that will be sending the traces

kubectl label namespace <name of the application namespace> SecureApplication-protected=full

Uninstall Instructions

Remove the label that was created during installation

kubectl label namespace <name of the application namespace> SecureApplication-protected-

Execute the script to delete the pod
```
./undeploy.sh
```

NGINX Ingress Controller

NGINX Ingress Controller

Configuring Panoptica to capture Trace Sources from an NGINX ingress controller is a simple matter of deploying a plugin to the cluster where Panoptica and NGINX are installed.

For more information about NGINX, please visit: Introduction to NGINX Ingress Controller

Prerequisites

NGINX Ingress Controller is running in your Kubernetes cluster
Panoptica API Security controller is installed in the same cluster

Environment variables

Replace the environment variables below with the appropriate values:

NGINX_NAMESPACE: namespace where the ingress controller is deployed.
Default: ingress-nginx
NGINX_RESOURCE_NAME: deployment name of the ingress controller.
Default: ingress-nginx-controller
NGINX_CM_NAME: configmap where the plugin will be enabled.
Default: Same as NGINX_RESOURCE_NAME
LUA_PLUGIN_PATH: the folder path which contains the plugin files.
Default: ./lua-plugin
MAX_REQUEST_BODY_SIZE: maximum request body size limit, in bytes.
Default: 1048576
MAX_RESPONSE_BODY_SIZE: maximum response body size limit, in bytes.
Default: 1048576

Install

To add the Panoptica Trace Source plugin to your NGINX deployment and Ingress configuration, run the following commands:

NGINX_NAMESPACE=<namespace> \
NGINX_RESOURCE_NAME=<name> \
NGINX_CM_NAME=<name> \
LUA_PLUGIN_PATH=<path> \
MAX_REQUEST_BODY_SIZE=<size in bytes> \
MAX_RESPONSE_BODY_SIZE=<size in bytes> \
./nginx-ingress-controller.sh deploy

Uninstall

To remove the plugin from your NGINX deployment, run the following commands:

NGINX_NAMESPACE=<namespace> \
NGINX_RESOURCE_NAME=<name> \
NGINX_CM_NAME=<name> \
./nginx.sh undeploy
./nginx-ingress-controller.sh undeploy

AWS API Gateway

AWS API Gateway

Since AWS does not support capturing Trace Sources directly from the API Gateway, Panoptica leverages CloudWatch to capture traces from your API Gateway logs. The logs are then streamed with Kinesis, processed by a Lambda function, then forwarded to Panoptica's Trace Controller. This is done by installing a plugin to your AWS API Gateway, either using CloudFormation or Terraform.

For more information about Amazon API Gateway, please see the Amazon API Gateway Developer Guide

📘
Limitations

Panoptica's AWS API Gateway solution uses the AWS Full Request and Response Logs option. According to Amazon, “Full Request and Response Logs can be useful to troubleshoot APIs, but can result in logging sensitive data. We recommend that you don't use Full Request and Response Logs for production APIs.”
For that reason, we recommend deploying this solution on Dev, Staging, or other non-production environments. See Setting up CloudWatch logging in the AWS Developer Guide for more details.

AWS API Gateway currently limits log events to 1024 bytes. Log events larger than 1024 bytes, such as request and response bodies, will be truncated by API Gateway before submission to CloudWatch logs.

Prerequisites

You have an Admin role to create resources in your AWS account
AWS Command Line Interface is installed and configured. See AWS Documentation for details.
Panoptica API Security controller is running, and exposed externally through a publicly reachable URL. See Exposing the API Controller for Trace Sources for details.
For Terraform installation only: Terraform version 1.5.7 or higher is installed

Environment variables

Replace the environment variables below with the appropriate values:

AWS_API_GATEWAY_CREATE_LOG_GROUP: A switch to control if a log group for the Gateway should be created in CloudWatch. If you already have a group, leave this on false; otherwise, set it to true.
Default: false
AWS_API_GATEWAY_ID: The ID of the AWS API Gateway where Panoptica's plugin will be configured
AWS_API_GATEWAY_STAGE_NAME: The name of the AWS API Gateway Stage from which Panoptica's plugin will collect data. For more information on stages, please see Setting up a stage in the AWS Developer Guide.
AWS_API_GATEWAY_CLOUDFORMATION_RESOURCES_STACK_NAME: The name of the Cloudformation stack for Panoptica's AWS API Gateway Plugin resources
Default: PanopticaApiGatewayPluginResources
AWS_API_GATEWAY_CLOUDFORMATION_LAMBDA_STACK_NAME: The name of the Cloudformation stack for Panoptica's AWS API Gateway Plugin lambda function
Default: PanopticaApiGatewayPluginLambda
AWS_API_GATEWAY_PLUGIN_LAMBDA_NAME: The name of Panoptica's AWS API Gateway Plugin lambda function
Default: PanopticaApiGatewayPlugin

Install

Panoptica's AWS API Gateway plugin can be installed using CloudFormation or Terraform. Both are included in the installation bundle you download from the API Trace Sources page in the Panoptica console.

CloudFormation

To deploy the AWS API Gateway plugin to your AWS account using CloudFormation, run the following commands. Replace the environment variables with the appropriate values above.

AWS_API_GATEWAY_CREATE_LOG_GROUP=<bool>  
AWS_API_GATEWAY_ID=\<api_gateway_id>  
AWS_API_GATEWAY_STAGE_NAME=\<api_gateway_stage_name>  
./awsgw_plugin.sh deploy

Terraform

To deploy the AWS API-Gateway plugin to your AWS account using Terraform, run the following commands. The Terraform code is found in a subfolder of the installation bundle. Replace the environment variables with the appropriate values above.

$ terraform plan  
    -var="create_api_gateway_log_group=false"  
    -var="api_gateway_id=\<api_gateway_id>"  
    -var="api_gateway_stage_name=\<api_gateway_stage_name>"  
    -var="upstream_telemetry_host_name=\<see_deploy_sh>"  
    -var="trace_source_token=\<see_deploy_sh>"  
    -out plan.tfplan  
$ terraform apply "plan.tfplan"

The value for the upstream_telemetry_host_name andtrace_source_tokenvariables can be taken from thedeploy.sh` file.
See the variables.tf file if you'd like to configure other resources.

Uninstall

Choose the appropriate uninstall script, according to whether you installed the plugin using CloudFormation or Terraform.

CloudFormation

To remove the AWS API Gateway plugin from your AWS account using CloudFormation, run the following commands:

AWS_API_GATEWAY_ID=\<api_gateway_id>  
AWS_API_GATEWAY_STAGE_NAME=\<api_gateway_stage_name>  
./awsgw_plugin.sh undeploy

Terraform

To remove the AWS API Gateway plugin from your AWS account using Terraform, run the following commands:

$ terraform plan  
    -destroy  
    -var="create_api_gateway_log_group=false"  
    -var="api_gateway_id=\<api_gateway_id>"  
    -var="api_gateway_stage_name=\<api_gateway_stage_name>"  
    -var="upstream_telemetry_host_name=\<see_deploy_sh>"  
    -var="trace_source_token=\<see_deploy_sh>"  
    -out destroy_plan.tfplan  
$ terraform apply "destroy_plan.tfplan"

Note: The aws_api_gateway_method_settings resource will be also destroyed. If you're writing API Gateway logs to CloudWatch, this setting will be turned off. You can exclude this resource from the terraform state, and configure API Gateway logging manually.

AWS VPC Mirroring

AWS VPC Mirroring

VPC Traffic Mirroring at AWS is used to monitor traffic between multiple EC2 instances. Panoptica's mirroring agent can collect TCP traffic from ENIs (Elastic Network interfaces) within the VPC, and forward it to Panoptica's API Security controller.

Follow the steps below to install a mirroring agent into your AWS VPC. For details about AWS VPC Traffic Mirroring, including the high level architecture and any limitations, please see the AWS documentation on Traffic Mirroring.

Prerequisites

You have an Admin role to create resources in your AWS account
AWS Command Line Interface (CLI) is installed and configured for the proper region. See AWS Documentation for details.
The subnets where the mirroring agent is being deployed have public access to pull the necessary container, and to send telemetries to Panoptica's API Security controller
The subnets where the source ENIs are located can communicate with the subnets where the agent is deployed
Panoptica API Security controller is deployed, and exposed externally through a publicly reachable URL. See Exposing the API Controller for Trace Sources for details.

Environment Variables

Replace the environment variables in the Install and Uninstall steps below with the appropriate values:

Name	Default value	Description
VPC_ID		The ID of the VPC where you want to do traffic mirroring
SUBNET_IDS		The ID of the subnets where the agent will be available, in different availability zones, separated by spaces. You can select one subnet per zone, the NLB and the ECS service will be available in these subnets.
SUBNETS_PUBLIC	false	If the subnets where the agent will be available are public and you would like to assign a public IP for the agent's ECS service, set this to `true`.
SOURCE_ENI_IDS		The ID of the network interfaces inside the VPC which you want to monitor, separated by spaces. Make sure that the communication between these ENIs and the target subnets are allowed.

Install

To deploy the agent and start the traffic mirroring, run the following script, replacing the variables with the relevant Environment Variables from the table above:

VPC_ID=<vpc_id> \
SUBNET_IDS=<subnet_id_1 subnet_id_2> \
SOURCE_ENI_IDS=<source_eni_id_1 source_eni_id_2> \
./aws_vpc.sh deploy

📘
Installation Process
This script will deploy every VPC mirroring-related resource, along with an NLB and ECS service for the agent for a given VPC. The installation takes around five minutes
You can monitor the progress on the CloudFormation tab in your AWS Management Console.
If you encounter any errors related to configuration, resolve them, delete the stacks and restart the process.

📘
Additional ENIs
If you want to monitor additional ENIs, or add new availability zones after running the above command, simply add them to the SOURCE_ENI_IDS and SUBNET_IDS lists and run the script again. It will calculate the diff and create the required resources.

These are the CloudFormation stacks that will be created:

PanopticaVpcMirroring-<VPC_ID>-NLB: The load balancer for the agent
PanopticaVpcMirroring-<VPC_ID>: The ECS service related resources for the agent and VPC mirroring configurations
PanopticaVpcMirroringSession-<ENI_ID>: For each ENI there will be a session stack which starts the mirroring between the source ENI and the agent

Installation Example

VPC_ID=vpc-06e735e36c159ecb3 
SUBNET_IDS="subnet-0c0a8bdce73c31050"
SOURCE_ENI_IDS="eni-0c6966f183b010c86 eni-085d3f69199cbc144"
./aws_vpc.sh deploy

Uninstall

To remove the mirroring agent from your AWS VPC, run the following script:

VPC_ID=\<vpc_id>  
SUBNET_IDS=\<subnet_id_1 subnet_id_2> 
SOURCE_ENI_IDS=\<source_eni_id_1 source_eni_id_2> 
./aws_vpc.sh undeploy

Alternatively, you can remove the mirroring agent manually by logging into your AWS Management Console and deleting the relevant stacks in the CloudFormation tab.

Limitations

Only resources that have a static ENI attached to them, such as EC2 instances, can be monitored using VPC Mirroring
There are additional costs incurred for traffic mirroring at AWS. Please see Traffic Mirroring - Pricing in the AWS Documentation for details.

F5 BIG-IP

Prerequisites

Environment variables

Install Instructions

Kong

Prerequisites

Environment variables

Install

Uninstall

Enable tracing

Ingress

Services

Preserving Client IP Address

Apigee X

Prerequisites

Automated installation

Prerequisites for automated installation

Usage

Install Instructions

Uninstall Instructions

Istio

Prerequisites

Install Instructions

Uninstall Instructions

NGINX Ingress Controller

Prerequisites

Environment variables

Install

Uninstall

AWS API Gateway

📘Limitations

Prerequisites

Environment variables

Install

CloudFormation

Terraform

Uninstall

CloudFormation

Terraform

AWS VPC Mirroring

Prerequisites

Environment Variables

Install

📘Installation Process

📘Additional ENIs

Installation Example

Uninstall

Limitations

📘
Limitations

📘
Installation Process

📘
Additional ENIs