#Configuration

Configuration variables can be defined at a few levels:

• Agent At an instance level, configured via agent.configure() or new Agent(), or when creating Handler agents using handler.createAgent() or handler.dispatchAgent().
• Connection At a connection level, which can be configured when creating a new ConnectionToCore.
• Core At an internal level, using the @secret-agent/core module of SecretAgent. This must be run in the environment where your Browser Engine(s) and @secret-agent/core module are running. If you're running remote, this will be your server.

The internal @secret-agent/core module can receive several configuration options on start, or when a Handler or Agent establishes a connection.

#Connection To Core

Agent

The ConnectionToCore to be used by a Handler or Agent.

All configurations accept both an options object and a ConnectionToCore instance.

Configuration is accepted in the following methods and constructors:

• agent.configure() - apply the connection to the default agent, or to a an agent constructed prior to the first connection.
• new Agent() - the new agent will use this connection.
• new Handler(...connections) - a handler takes one or more coreClientConnection options or instances.

#Max Concurrent Agents Count

Core

Limit concurrent Agents operating at any given time across all connections to a "Core". Defaults to 10.

Configurable via Core.start() or ConnectionToCore.

#Local Proxy Port Start

ConnectionCore

Configures the port the Man-In-the-Middle server will listen on locally. This server will correct headers and TLS signatures sent by requests to properly emulate the desired browser engine. Default port is 0, which will find an open port locally.

Configurable via Core.start() or the first ConnectionToCore.

#Replay Session Port

ConnectionCore

Configures the port Replay uses to serve Session data.

Configurable via Core.start() or the first ConnectionToCore.

#Sessions Dir

ConnectionCore

Configures the storage location for files created by Core.

• Replay session files
• Man-in-the-middle network certificates

Environmental variable: SA_SESSIONS_DIR=/your-absolute-dir-path

Configurable via Core.start() or the first ConnectionToCore.

#Blocked Resource Types

ConnectionAgent

One of the best ways to optimize SecretAgent's memory and CPU is setting blockedResourceTypes to block resources you don't need. The following are valid options.

As you'll notice above, some features are dependent on others and therefore automatically enable other features.

Setting an empty array is the same as setting to None.

#User Profile

ConnectionAgent

A user profile stores and restores Cookies, DOM Storage and IndexedDB records for an Agent. NOTE: the serialized user profile passed into an Agent instance is never modified. If you want to update a profile with changes, you should re-export and save it to the format you're persisting to.

const rawProfileJson = fs.readFileSync('profile.json', 'utf-8');
const profile = JSON.parse(rawProfileJson); // { cookies: { sessionId: 'test' }}

agent.configure({ userProfile: profile });
const latestUserProfile = await agent.exportUserProfile();
// { cookies, localStorage, sessionStorage, indexedDBs }

await agent.goto('http://example.com');

const latestUserProfile = await agent.exportUserProfile();

fs.writeFileSync('profile.json', JSON.stringify(latestUserProfile, null, 2));

#Upstream Proxy

Agent

Configures a proxy url to route traffic through for a given Agent. This function supports two types of proxies:

• Socks5 - many VPN providers allow you to use a socks5 configuration to send traffic through one of their VPNs behind the scenes. You can pass any required username and password through the UserInfo portion of the url, e.g., socks5://username:password@sockshost.com:1080.
• Http - an http proxy will create secure TLS socket to an upstream server using the HTTP connect verb. Services like luminati provide highly configurable Http proxies that can route traffic from various geographic locations and "grade" of IP - ie, consumer IP vs datacenter.

An upstream proxy url should be a fully formatted url to the proxy. If your proxy is socks5, start it with socks5://, http http:// or https:// as needed. An upstream proxy url can optionally include the user authentication parameters in the url. It will be parsed out and used as the authentication.

#Browsers Emulator Id

Agent

Configures which BrowserEmulator to use in a given Agent.

#Human Emulator Id

Agent

Configures which HumanEmulator to use in an Agent instance.

#Core Configuration

Configuration for Core should be performed before initialization.

#Core.start(options)

Update existing settings.

#Arguments:

• options object Accepts any of the following:
  • maxConcurrentAgentsCount number defaults to 10. Limit concurrent Agent sessions running at any given time.
  • localProxyPortStart number defaults to any open port. Starting internal port to use for the mitm proxy.
  • sessionsDir string defaults to os.tmpdir()/.secret-agent. Directory to store session files and mitm certificates.
  • coreServerPort number. Port to run the Core Websocket/Replay server on.

#Returns: Promise