API Reference

Complete reference for Sentry, TrapBuilder, and WatchBuilder.

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)

InstallSentry(router, service, environment string) *App

Import path varies by framework:

• github.com/trappsec-dev/trappsec/packages/go/gin
• github.com/trappsec-dev/trappsec/packages/go/nethttp
• github.com/trappsec-dev/trappsec/packages/go/echo

Initializes the trappsec Sentry.

• app / router: The application or router instance (Flask/FastAPI/Express/NestJS/gin.Engine/http.ServeMux/*echo.Echo).
• 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");

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");

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,
})

trap.Respond(trappsec.ResponseConfig{
    Status: int, Body: any,
    MIMEType: 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" });

trap.Respond(trappsec.ResponseConfig{
    Status: 200, Body: map[string]any{"status": "ok"},
})
trap.Respond(trappsec.ResponseConfig{
    Status: 403, Body: "Access Denied", MIMEType: "text/plain",
})
trap.Respond(trappsec.ResponseConfig{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,
})

trap.IfUnauthenticated(trappsec.ResponseConfig{
    Status: int, Body: any,
    MIMEType: string, Template: string,
})

Example

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

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

trap.IfUnauthenticated(trappsec.ResponseConfig{
    Status: 401,
    Body:   map[string]any{"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 })

watch.Body(name string, defaultValue any, intent string)

Example

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

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

// Alert on any presence of 'is_admin'
watch.Body("is_admin", trappsec.NoDefault, "PrivEsc")

// Alert only if value differs from default
watch.Body("is_admin", false, "PrivEsc")

• name: The field name to watch.
• default / defaultValue: (Optional) If provided, alerts only if the value differs from this default. If omitted (or trappsec.NoDefault in Go), 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"
}));

ts.IdentifyUser(func(req any) *trappsec.AuthContext {
    c := req.(*gin.Context) // cast to your framework's request type
    uid := c.GetHeader("x-user-id")
    if uid == "" {
        return nil // unauthenticated
    }
    return &trappsec.AuthContext{User: uid, Role: c.GetHeader("x-user-role")}
})

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);

ts.OverrideSourceIP(func(req any) string {
    c := req.(*gin.Context)
    if ip := c.GetHeader("x-real-ip"); ip != "" {
        return ip
    }
    return c.ClientIP()
})

add_webhook

Adds a webhook destination for alerts.

ts.add_webhook("https://...")
ts.add_webhook("https://...", alerts_only=False)

ts.add_webhook("https://...");
ts.add_webhook("https://...", { alerts_only: false });

ts.AddWebhook("https://...", nil)
// Send all events (not just alerts)
alertsOnly := false
ts.AddWebhook("https://...", &trappsec.WebhookOptions{AlertsOnly: &alertsOnly})

By default, webhook integration is alerts_only=true, so only events with type="alert" are delivered. Set alerts_only to false in add_webhook options to forward both alert and signal events.

add_slack

Adds a Slack-optimized output using an incoming webhook URL.

ts.add_slack("https://hooks.slack.com/services/...")
ts.add_slack("https://hooks.slack.com/services/...", alerts_only=False)

ts.add_slack("https://hooks.slack.com/services/...");
ts.add_slack("https://hooks.slack.com/services/...", { alerts_only: false });

ts.AddSlack("https://hooks.slack.com/services/...", nil)
// Send all events (not just alerts)
alertsOnly := false
ts.AddSlack(
    "https://hooks.slack.com/services/...",
    &trappsec.SlackOptions{AlertsOnly: &alertsOnly},
)

add_otel

Enables OpenTelemetry integration for alerts.

ts.add_otel()

ts.add_otel();

ts.AddOTEL()