Request Interceptor

Introduction

The server-side request interceptor, implemented as a TypeScript module, allows developers to intercept and modify outgoing HTTP GET requests for remote PCAPs before they are sent. The interceptor is designed to be flexible, enabling the modification of both the target URL and the HTTP headers of the request. This outline describes the structure of the interceptor, including its key interfaces, types, and the main function signature, serving as a template for implementing custom request modifications.

Why TypeScript?

TypeScript is used to provide strong typing and improved developer experience, ensuring type safety and enabling better code completion and error detection during development. Also, as the front-end of Packet Viewer is written in TypeScript, there is a high likelihood that developers are familiar with it already.

TypeScript allows developers to create more robust and maintainable interceptor implementations with reduced runtime errors. TypeScript is also able to be executed internally within the Packet Viewer API server, requiring no external dependencies.

Adding your code to the Docker container

You need to ensure your interceptor TypeScript file is available inside the container before starting the server. We recommend using the /config directory for storing such scripts.

Sample Dockerfile

FROM packet-viewer:v1.7.0
COPY ./your_local_interceptor.ts /config/interceptor.ts

Then rebuild:

docker build . -t your_pv_image_name

Enabling the interceptor module

To enable the request interceptor, use the following command-line flag when starting the server:

--request-interceptor /config/interceptor.ts

You may also use environment variables or another configuration method to set this option.

TypeScript Interfaces

ApiRequest

Represents the original API request that triggered the PCAP fetch.

Properties:

• url: string
• remote_host: string
• headers: HTTPHeaders

InterceptResult

Returned by the intercept function to control how the API server fetches remote data.

Properties:

• url?: string
• headers?: HTTPHeaders

If url or headers is undefined, the original values are not modified before sending.

HTTPHeaders

Represents HTTP headers as key-value pairs.

type HTTPHeaders = {
  [key: string]: string[] | string;
};

Interceptor

Defines the signature of the expected default export.

/** A function that takes a URL and original API Request
 * and returns the InterceptResult
 */
type Interceptor = (url: string, r: ApiRequest) => InterceptResult;

Default Export

Your TypeScript module should export a single default function which matches the Interceptor type. The default export is executed for every PCAP fetch that the server needs to make to retrieve data from a remote source.

export default (uri: string, r: ApiRequest): InterceptResult => {
  // your implementation here
};

This function takes two parameters:

1. uri: string - The original URI
2. r: ApiRequest - The original API request details

It should return an InterceptResult object.

Example Implementation

export default (url: string, r: ApiRequest): InterceptResult => {
  return {
    url: url,
    headers: {
      Cookie: r.headers["Cookie"],
      "X-Forwarded-For": r.remote_host,
    },
  };
};

The provided example implementation:

• Passes through the requested url with no modifications,
• Adds all cookies from the original client request
• Adds an X-Forwarded-For header with the original remote host address