Trace Source Installation

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

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

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

  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

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

  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 accessible from your AWS cluster
  • 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.