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

1. 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.

2. 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

3. 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

4. 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

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

Install this plugin to integrate Panoptica with your Apigee X platform. Once installed, the plugin will capture API traffic from Apigee X via a shared flow, and forward it to the API Security controller.

You can choose either the Automated Installation, or the Manual Installation below.

For more information about Apigee X please visit: https://cloud.google.com/apigee/docs

Prerequisites

• Panoptica API Security controller running and exposed externally through a publicly reachable URL
• There is an Apigee X proxy configured in your GCP account, with connectivity to the Panoptica API Security controller.

Automated installation

Select this method to deploy the plugin automatically.

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 run the script below. See API Trace Sources for details.

You can retrieve the Google Cloud access token by running the following command in gcloud: gcloud auth print-access-token

• To install the plugin

  APIGEE_ENVIRONMENT=<environment-name> \
  APIGEE_ORGANIZATION=<organization-name> \
  APIGEE_TOKEN=<google-cloud-token> \
  ./apigee.sh deploy
  

• To uninstall the plugin

  APIGEE_ENVIRONMENT=<environment-name> \
  APIGEE_ORGANIZATION=<organization-name> \
  APIGEE_TOKEN=<google-cloud-token> \
  ./apigee.sh undeploy
  

Manual installation

You can also install the Panoptica Apigee X plugin manually, using either the Apigee UI or Google Cloud Console. In either platform, you first deploy the certificate, then configure the shared flow.

Apigee UI

1. Add Certificate to Apigee X
   1. Log into the Apigee console
   2. Go to Admin->Environments->TLS Keystores and create a keystore named Panoptica
   3. Create an Alias named Panoptica and upload the Panoptica public certificate, found in the bundle you downloaded from the Panoptica platform.
   4. In Admin->Environments->References, create a reference named panopticaRef that references the certificate named Panoptica you just created.
2. Configure the shared flow bundle
   1. Upload the bundle:
      • Go to Develop->Shared Flows and upload a bundle
      • Select to upload the file sharedflowbundle.zip, which you'll also find in the bundle you downloaded from Panoptica. Name the upload PanopticaFlowBundle.
   2. Deploy the shared flow created by the bundle
   3. Go to Admin->Environments->Flow Hooks and associate the shared flow to the Post-proxy hook

Google Cloud Console

1. Add Certificate to Apigee X
   1. Log into the Google Cloud console
   2. Go to Environments under the Management group in the sidebar, select your environment, choose TLS Keystores tab and create a keystore named Panoptica
   3. Create an Alias named Panoptica with the plus sign in the actions column, and upload the Panoptica public certificate, found in the bundle you downloaded from the Panoptica platform.
   4. In the Environments References tab, create a reference named panopticaRef that refers the certificate named Panoptica you previously created.
2. Configure the shared flow bundle
   1. Upload the bundle:
      • Go to Shared Flows under the Proxy Deployment group in the sidebar and upload a bundle
      • Select to upload the file sharedflowbundle.zip, which you'll also find in the bundle you downloaded from Panoptica. Name the upload PanopticaFlowBundle.
   2. Deploy the shared flow created by the bundle
   3. Go to Flow Hooks tab in your environment and associate the shared flow to the Post-proxy hook

Manual Uninstall

You can uninstall the Apigee X plugin using the automated undeploy script above, even if you installed it manually via a web interface. To uninstall via Apigee UI or Google Cloud Console, back out the same steps you performed to deploy, in reverse order.

Apigee UI

1. Delete the shared flow bundle
   1. Go to Admin->Environments->Flow Hooks and unassociate the shared flow in the Post-proxy hook.
   2. Go to Develop->Shared Flows, select and delete the bundle.
2. Remove Certificate from Apigee X
   1. In Admin->Environments->References, delete the reference named panopticaRef, that refers to the certificate named Panoptica you created previously.
   2. Go to Admin->Environments->TLS Keystores and delete the keystore with the alias Panoptica.

Google Cloud Console

1. Delete the shared flow bundle
   1. Go to Flow Hooks tab in your environment and unassociate the shared flow from the Post-proxy hook
   2. Go to Shared Flows under the Proxy Deployment group in the sidebar and delete the bundle..
2. Remove Certificate from Apigee X
   1. In the Environments References tab, delete the reference named panopticaRef, that refers to the certificate named Panoptica you created previously.
   2. Go to Environments under the Management group in the sidebar, select your environment, choose TLS Keystores tab and delete the keystore named Panoptica.

Apigee X limitations

The Panoptica plugin is subject to the following limitations, which are set by Apigee X.
See https://cloud.google.com/apigee/docs/api-platform/reference/limits for details.

• Header size: 60 KB limit, enforced on:
  • Request header​
  • Response header​
• Body size: 10 MB limit on non-streamed requests, enforced on:
  • Request body​
  • Response body​

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

1. Download the Istio bundle and execute the script to create the pod

   ./deploy.sh
   

2. 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

1. Remove the label that was created during installation

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

2. Execute the script to delete the pod

   ./undeploy.sh
   

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

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

1. 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.
2. 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

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:

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.