Traceable Apigee Blocking Agent Installation (Legacy)

Note: This documentation applies to apigee-blocking agent versions prior to 1.38.0, which use the ExtCapReqCapSC policy and the ext_cap/v1/req_cap endpoint.

If you are using version 1.38.0 or later, refer to the current Blocking Agent Installation documentation, which uses the updated EvaluateBlockingSC policy and the ext_cap/v1/evaluate_blocking endpoint.

Overview

Traceable's Apigee blocking agent allows you to monitor and secure your API traffic by deploying a shared flow in Apigee. The agent can be deployed as a shared flow and attached to all or specific API proxies for comprehensive security and observability.

Installation

Downloading the Traceable Policy

Download the Traceable policy for Apigee from Traceable download site. Navigate to agent → apigee-blocking → latest to download the traceable-blocking-shareflow.zip file for the blocking agent. Save the file.

Policy Files

The downloaded archive contains the following policy files for the blocking agent:

• ExportSpansSC.xml

• ExportSpansML.xml

• ExportSpansJS.xml

• ExtCapReqCapSC.xml

• ExtCapReqCapResponseEV.xml

• ReturnedBlockedResponseRF.xml

• TraceableJS.xml

Adding the Shared Flow

Complete the following steps to add Traceable's Shared Flow:

• Login to your Apigee account.

• In the proxy development section, navigate to SharedFlows.

• Add a new SharedFlow. Click on Upload Bundle. Navigate to the location where you have downloaded Traceable's Apigee policy.

Configuring the Shared Flow

• Click on the imported SharedFlow and navigate to the Develop tab.

• Click on the ExportSpansML/ExportSpansSC and TraceableJS policy and update the configuration values. In ExportSpansML/ExportSpansSC, configuring the Traceable Platform agent IP address or hostname is mandatory. The other configurations are optional.

• In the case of the blocking agent click on the ExtCapReqCapSC file and configure the Traceable Platform agent host or IP address.

• Save and Deploy the SharedFlow — Click the save button then the Deploy button and select the environment where you wish to deploy the agent. This will deploy the agent as a SharedFlow to that environment.

Adding the Shared Flow to API Proxies

Adding to All API Proxies Using Flow Hooks

1. Navigate to the Environments tab in the Management section.

2. Edit the Flow Hooks and attach the traceable-agent shared flow to Pre-proxy, Pre-target, Post-target, and Post-proxy Flow Hooks. This will attach the Traceable agent with all API Proxies where the flow hook has been added.

Attaching Traceable Agent to a Specific API Proxy

1. Navigate to the API Proxy to which you wish to attach the Traceable Apigee agent and click on the Develop tab.

2. Click on Add a policy (the + sign beside Policies).

3. Select Policy Type Flow Callout and select traceable-shared-flow from the list of shared flows.

4. Add the Traceable policy to all the flows (pre and post proxy flows, and pre and post target flows), keeping the following in mind:

   • Traceable policy should be the first one in Proxy → Request → Preflow.

   • Traceable policy should be the last one in Target → Request → Preflow.

   • Traceable policy should be the first one in Target → Response → Postflow.

   • Traceable policy should be the last one in Proxy → Response → Postflow.

   Note: The above four places are where the Traceable policy needs to be added.

5. Add a Fault Rule in both the Proxy Endpoints and Target Endpoints in XML as follows. Update the name of the flow callout policy:

   <FaultRules>
       <FaultRule name="traceable fault rule">
           <Step>
               <Name>NAME_OF_TRACEABLE_FLOW_CALLOUT_POLICY_ADDED_ABOVE</Name>
           </Step>
       </FaultRule>
   </FaultRules>

6. Save and deploy the proxy.

Enabling SSL

Configure the following field in policies which are exporting data to the platform agent if SSL needs to be enabled:

<SSLInfo>
    <Enabled>false</Enabled>
    <ClientAuthEnabled>false</ClientAuthEnabled>
    <TrustStore>ref://give_your_truststore_reference</TrustStore>
    <IgnoreValidationErrors>false</IgnoreValidationErrors>
</SSLInfo>

Key changes and explanations:

• <Enabled>true</Enabled> - This enables SSL/TLS for the connection to your log server

• <ClientAuthEnabled>false</ClientAuthEnabled> - Keep this as false unless your log server specifically requires client certificate authentication (mutual TLS). Most log servers only need server-side SSL.

• <TrustStore>ref://your-truststore-reference</TrustStore> - Replace your-truststore-reference with the actual reference name of a truststore you've created in Apigee that contains the CA certificates needed to validate your log server's SSL certificate.

• <IgnoreValidationErrors>false</IgnoreValidationErrors> - Keep this as false for security. Setting it to true would skip SSL certificate validation, which defeats the purpose of using SSL.

Message Logging Policy Usage

In your Platform agent deployment, ensure the Apigee log server is enabled. Edit the config.yaml file to configure the following:

global:
  apigee_server:
    enabled: true
    message_end_token: "__SPAN_END__"
    server:
      endpoint: "0.0.0.0:8444"
      key_file: ""
      cert_file: ""
      max_queue_size: 1000
      max_buffer_size: 1024

Note: Ensure that port 8444 (or the configured port for the Apigee log server) of the instance where the Platform agent is installed is accessible from the Apigee servers.

The port of the Apigee log server is a TCP port. Make sure that from your Apigee setup, there is outgoing data access to the TCP port of the Apigee log server (part of the Platform agent).

Also configure the host field in the ExportSpansML policy:

<Syslog>
    <Message>{TRACEABLE_DATA}__SPAN_END__</Message>
    <!-- Host IP/address TPA -->
    <Host>[TPA_IP]</Host>
</Syslog>

ExtCapReqCapSC Policy usage

Set the IP address of TPA in the following field

<HTTPTargetConnection>
  <!-- The URL would be https://TPA_HOST:5443/ext_cap/v1/req_cap in case of TLS configuration -->
  <URL>http://TPA_HOST:5442/ext_cap/v1/req_cap</URL>
</HTTPTargetConnection>

ExportSpansSC Usage

Configure the following fields when this policy is being used

<Request>
    <!-- Configure the timeout in milliseconds -->
    <Timeout>250</Timeout>
    <HTTPTargetConnection>
        <!-- The URL would be https://TPA_HOST:5443/ext_cap/v1/res_cap in case of TLS configuration -->
        <URL>http://TPA_HOST:5442/ext_cap/v1/res_cap</URL>
    </HTTPTargetConnection>
</Request>

PostClientFlow deployment

Optionally, you can attach the policy on PostClientFlow as well, if you want the response capture call to TPA to be made after the response is sent back to the client.

1. You have already attached our shared flow to PreProxy, PreTarget, PostTarget, PostProxy. Now attach it to PostClientFlow as well, as in the screenshot below.

2. Update the sharedflow default.xml as given below. Save and deploy the sharedflow.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<SharedFlow name="default">
    <Step>
        <Condition>current.flow.name != "PostClientFlow"</Condition>
        <Name>TraceableJS</Name>
    </Step>
    <Step>
        <Condition>(TA_FLOW_VALUE = 2) and (TA_REQ_CAP_REQUEST != null)</Condition>
        <Name>ExtCapReqCapSC</Name>
    </Step>
    <Step>
        <Condition>(TA_FLOW_VALUE = 2) and (TA_REQ_CAP_RESPONSE != null)</Condition>
        <Name>ExtCapReqCapResponseEV</Name>
    </Step>
    <Step>
        <Condition>(TA_FLOW_VALUE = 2) and (TA_ALLOW_REQUEST = "false")</Condition>
        <Name>ReturnBlockedResponseRF</Name>
    </Step>
    <Step>
        <Condition>(TRACEABLE_DATA != null) and (current.flow.name = "PostClientFlow") and (TA_ALLOW_REQUEST != "false") and (TA_SPAN_TYPE != "nospan") and (TA_REPORTING_TRACE_REPORTER_TYPE = "message_logging")</Condition>
        <Name>ExportSpansML</Name>
    </Step>
    <Step>
        <Condition>(TRACEABLE_DATA != null) and (current.flow.name = "PostClientFlow") and (TA_ALLOW_REQUEST != "false") and (TA_SPAN_TYPE != "nospan") and (TA_REPORTING_TRACE_REPORTER_TYPE = "service_callout")</Condition>
        <Name>ExportSpansSC</Name>
    </Step>
    <Step>
        <Condition>(TRACEABLE_DATA != null) and (current.flow.name = "PostClientFlow") and (TA_ALLOW_REQUEST != "false") and (TA_SPAN_TYPE != "nospan") and (TA_REPORTING_TRACE_REPORTER_TYPE = "javascript_callout")</Condition>
        <Name>ExportSpansJS</Name>
    </Step>
</SharedFlow>