API Reference

This reference documents the core classes and methods available in the trappsec SDK.

Sentry

The main entry point for the library.

Sentry(app, service: str, environment: str)

new Sentry(app, service, environment)

Initializes the trappsec Sentry.

• app: The application instance (Flask/FastAPI/Express).
• service: Name of your service (e.g., “PaymentService”).
• environment: Deployment environment (e.g., “Production”, “Staging”).

TrapBuilder

Returned by ts.trap(path). Used to configure a decoy route.

methods

trap.methods("GET", "POST")

trap.methods("GET", "POST");

Specifies the HTTP methods this trap should accept. Defaults to ["GET", "POST"].

intent

trap.intent("Credential Harvesting")

trap.intent("Credential Harvesting");

Sets the intent label for alerts generated by this trap.

respond

Configures the response sent to authenticated requests. Unauthenticated requests will receive a default 401 Unauthorized response (which you can override globally or per-trap using if_unauthenticated).

Signature

trap.respond(status: int, body: dict | str | Callable, mime_type: str = None, template: str = None)

trap.respond({ status: number, body: object | string | Function, mime_type: string, template: string })

Examples

trap.respond(200, {"status": "ok"})
trap.respond(403, "Access Denied", mime_type="text/plain")
trap.respond(template="deprecated_api")

trap.respond({ status: 200, body: { "status": "ok" } });
trap.respond({ status: 403, body: "Access Denied", mime_type: "text/plain" });
trap.respond({ template: "deprecated_api" });

• status: HTTP status code.
• body: JSON object, string, or a function returning one of those.
• mime_type: Content-Type header (defaults to “application/json”). You must explicitly set this to “text/plain” (or others) if returning a non-JSON body.
• template: Name of a registered response template.

if_unauthenticated

Configures a specific response for unauthenticated requests. Overrides respond for unauthenticated traffic.

Signature

trap.if_unauthenticated(status: int, body: dict | Callable, mime_type: str = None, template: str = None)

trap.if_unauthenticated({ status: number, body: object | Function, mime_type: string, template: string })

Example

trap.if_unauthenticated(401, {"error": "Login Required"})

trap.if_unauthenticated({ status: 401, body: { "error": "Login Required" } });

WatchBuilder

Returned by ts.watch(path). Used to configure honey fields on legitimate routes.

body

Monitors the request body for specific keys.

Signature

watch.body(name: str, default: Any = NO_DEFAULT, intent: str = None)

watch.body(name, { defaultValue: any, intent: string })

Example

watch.body("is_admin", default=False, intent="PrivEsc")

watch.body("is_admin", { defaultValue: false, intent: "PrivEsc" });

• name: The field name to watch.
• default: (Optional) If provided, alerts only if the value differs from this default. If omitted, alerts on any presence of the key.
• intent: The intent label for the alert.

Configuration

Global configuration methods.

identify_user

Registers a callback to extract user identity from the request.

# Extract user info from your authentication middleware (e.g. Flask-Login, JWT)
ts.identify_user(lambda r: {
    "id": getattr(r.user, "id", None), 
    "role": getattr(r.user, "role", "guest")
})

// Extract user info from your authentication middleware (e.g. Passport, Clerk)
ts.identify_user((req) => ({ 
    "id": req.user?.id,
    "role": req.user?.role || "guest"
}));

override_source_ip

Registers a callback to extract the real client IP (e.g., from X-Forwarded-For).

ts.override_source_ip(lambda r: r.remote_addr)

ts.override_source_ip((req) => req.ip);

add_webhook

Adds a webhook destination for alerts.

ts.add_webhook("https://...")

ts.add_webhook("https://...");

add_otel

Enables OpenTelemetry integration for alerts.

ts.add_otel()

ts.add_otel();