create_interactsh_session

Creates callback domains for out-of-band interaction testing, enabling security testing and verification workflows by capturing DNS/HTTP interactions.

Instructions

Generates credentials, registers with interactsh, and returns the connection details.

Input Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Implementation Reference

src/server.js:302-330 (handler)

MCP tool handler for create_interactsh_session. Creates a new interactsh session using the service, generates a sample probe host and detailed instructions, then returns a formatted result.

async () => {
  const session = await service.createSession();
  const baseDomain = service.domainSuffix || new URL(service.baseUrl).hostname;
  const probeNonce = crypto
    .randomBytes(16)
    .toString('base64')
    .replace(/[^a-z0-9]/gi, '')
    .slice(0, 13)
    .toLowerCase();
  const probeHost = `${session.correlationId}${probeNonce}.${baseDomain}`;
  const instructions = [
    'Probing rules (very important):',
    '- Build the host as: <correlation_id><nonce13>.<domain>',
    '- correlation_id: exactly 20 lowercase hex characters (do not alter or truncate).',
    "- nonce13: exactly 13 lowercase alphanumeric characters [a-z0-9] (no hyphens or uppercase).",
    '- The label before the first dot must be length 33 (20 + 13).',
    '- Requests to only <correlation_id>.<domain> (no nonce) will be ignored by interactsh.',
    '',
    `Quick test (HTTP recommended): curl -I http://${probeHost}/`,
    'Then wait 2–3 seconds and call poll_interactsh_session with the same correlation_id to retrieve events.',
    'If you still get zero events, send another probe or use filters (method, protocol, path_contains, text_contains) when polling.',
  ].join('\n');

  return result({
    ...session.toJSON(),
    instructions,
    sample_probe_host: probeHost,
  });
},

src/server.js:296-331 (registration)

Registration of the create_interactsh_session tool with the MCP server via server.registerTool, including title, description, and handler function.

server.registerTool(
  'create_interactsh_session',
  {
    title: 'Create interactsh session',
    description: 'Generates credentials, registers with interactsh, and returns the connection details.',
  },
  async () => {
    const session = await service.createSession();
    const baseDomain = service.domainSuffix || new URL(service.baseUrl).hostname;
    const probeNonce = crypto
      .randomBytes(16)
      .toString('base64')
      .replace(/[^a-z0-9]/gi, '')
      .slice(0, 13)
      .toLowerCase();
    const probeHost = `${session.correlationId}${probeNonce}.${baseDomain}`;
    const instructions = [
      'Probing rules (very important):',
      '- Build the host as: <correlation_id><nonce13>.<domain>',
      '- correlation_id: exactly 20 lowercase hex characters (do not alter or truncate).',
      "- nonce13: exactly 13 lowercase alphanumeric characters [a-z0-9] (no hyphens or uppercase).",
      '- The label before the first dot must be length 33 (20 + 13).',
      '- Requests to only <correlation_id>.<domain> (no nonce) will be ignored by interactsh.',
      '',
      `Quick test (HTTP recommended): curl -I http://${probeHost}/`,
      'Then wait 2–3 seconds and call poll_interactsh_session with the same correlation_id to retrieve events.',
      'If you still get zero events, send another probe or use filters (method, protocol, path_contains, text_contains) when polling.',
    ].join('\n');

    return result({
      ...session.toJSON(),
      instructions,
      sample_probe_host: probeHost,
    });
  },
);

src/server.js:39-63 (helper)

Core logic for creating an interactsh session in InteractshService class: generates RSA keys, correlation ID, secret key, creates session object, registers it, and stores in map.

async createSession() {
  const { publicKey, privateKey } = crypto.generateKeyPairSync('rsa', {
    modulusLength: 2048,
    publicExponent: 0x10001,
  });

  const publicKeyPem = publicKey.export({ type: 'spki', format: 'pem' });
  const publicKeyB64 = Buffer.from(publicKeyPem).toString('base64');
  const correlationId = this.#generateCorrelationId();
  const secretKey = this.#generateSecretKey();
  const callbackDomain = this.domainSuffix ? `${correlationId}.${this.domainSuffix}` : correlationId;

  const session = new InteractshSession({
    correlationId,
    secretKey,
    privateKey,
    publicKeyB64,
    callbackDomain,
    serverUrl: this.baseUrl,
  });

  await this.#register(session);
  this.sessions.set(correlationId, session);
  return session;
}

src/server.js:10-29 (helper)

InteractshSession class used to hold session data and provide JSON serialization for the tool output.

export class InteractshSession {
  constructor({ correlationId, secretKey, privateKey, publicKeyB64, callbackDomain, serverUrl }) {
    this.correlationId = correlationId;
    this.secretKey = secretKey;
    this.privateKey = privateKey;
    this.publicKeyB64 = publicKeyB64;
    this.callbackDomain = callbackDomain;
    this.serverUrl = serverUrl;
  }

  toJSON() {
    return {
      correlation_id: this.correlationId,
      secret_key: this.secretKey,
      private_key_pem: this.privateKey.export({ type: 'pkcs8', format: 'pem' }),
      callback_domain: this.callbackDomain,
      server_url: this.serverUrl,
    };
  }
}

MCP Interactsh Bridge