Windows IIS Agent

The Treblle IIS Agent is a native C++ module for Windows Server 2022 / 2025 that passively monitors JSON API traffic and sends data to Treblle. It hooks into the IIS request pipeline via a DLL, giving you full API observability with zero impact on availability or latency.

IIS Worker Process (w3wp.exe)
  └── TreblleAgent.dll
        ├── OnBeginRequest   → route check → capture request headers + body
        ├── OnSendResponse   → capture response headers + body chunks
        └── OnEndRequest     → build JSON payload → push to background queue
                                    │
                                    └── Background thread
                                          └── WinHTTP HTTPS POST → ingress.treblle.com

Prerequisites

You will also need a Treblle account with an API Key and SDK Token.

Security

Code signing

Every TreblleAgent.dll on the Releases page  is digitally signed (Authenticode) with a Sectigo OV code signing certificate issued to Treblle. OV means Sectigo verified Treblle as a real, registered company before issuing it. The signature is also timestamped, so it stays valid even after the certificate itself expires.

The practical benefit: Windows and your security tools can see exactly who published the DLL, so it is treated as software from a known company rather than an unknown file. That usually means fewer security exceptions for your team to request before the agent can run:

• Antivirus and EDR (endpoint detection and response) - signed binaries rarely trigger the false positives that unsigned native DLLs do, so you typically do not need a per-file allowlist entry
• AppLocker and WDAC (Windows Defender Application Control) - you can allow the agent with a publisher rule for Treblle, which keeps working across updates, instead of a file hash rule that has to be updated every time the DLL changes
• SmartScreen - a signed file from a known publisher is not flagged as an app from an unrecognized publisher

You do not have to do anything with the signature. Windows and your security tools check it automatically. If you or your security team want to see it for yourselves, this is optional but easy:

Get-AuthenticodeSignature -FilePath "TreblleAgent.dll" | Format-List Status, StatusMessage, SignerCertificate, TimeStamperCertificate

Status should come back as Valid, and the signer certificate should be issued to Treblle. If you have the Windows SDK installed, signtool shows the same result plus the full certificate chain:

signtool verify /pa /v "TreblleAgent.dll"

Installation

Step 1 - Download the agent

From the Releases page , download two things:

1. TreblleAgent.dll - the agent itself, code-signed by Treblle
2. The installer package, which contains the installer\ folder with install.ps1 and uninstall.ps1

Put TreblleAgent.dll inside the installer\ folder so both sit next to each other.

Unblock-File -Path "TreblleAgent.dll"

Step 2 - Run the installer

Open PowerShell as Administrator, go to the installer\ folder, and run the install script:

# Right-click PowerShell → Run as Administrator
cd path\to\installer
.\install.ps1

Set-ExecutionPolicy -ExecutionPolicy Bypass -Scope Process
.\install.ps1

The installer will:

• Copy TreblleAgent.dll to C:\iismodules\treblle\
• Prompt you for your API Key, SDK Token, and optional exclusion patterns
• Write C:\iismodules\treblle\treblle.config
• Register the agent globally in IIS, so it applies to every site on the server
• Restart IIS

Step 3 - Grant app-pool permissions (if needed)

On some servers, the new C:\iismodules\treblle\ folder does not inherit permissions for the accounts IIS worker processes run as, so IIS cannot read the DLL and fails to load it. If IIS does not start after installation, give those accounts read and execute access:

# Covers every application pool via the built-in IIS_IUSRS group (recommended)
icacls "C:\iismodules\treblle" /grant "IIS_IUSRS:(OI)(CI)RX" /T
 
# Alternative - grant a single named application pool only
icacls "C:\iismodules\treblle" /grant "IIS AppPool\DefaultAppPool:(OI)(CI)RX" /T

Replace DefaultAppPool with the name of your app pool. To list all pools:

%windir%\system32\inetsrv\appcmd.exe list apppool

Then restart IIS:

iisreset

Step 4 - Verify

List the registered IIS modules and look for TreblleAgent:

%windir%\system32\inetsrv\appcmd.exe list module
# Should include:
# MODULE "TreblleAgent" (image:C:\iismodules\treblle\TreblleAgent.dll)

Make a request to one of your API endpoints and check your Treblle dashboard .

Configuration

The config file lives at C:\iismodules\treblle\treblle.config. Edits take effect immediately - the agent notices the file has changed and reloads it on the next request, so there is no need to restart IIS.

{
  "api_key":    "YOUR_TREBLLE_API_KEY",
  "sdk_token":  "YOUR_TREBLLE_SDK_TOKEN",
  "treblle_url": "https://ingress.treblle.com",
  "debug": false,
  "disabled": false,
  "exclude_routes": [
    { "host": "internal.yourdomain.com" },
    { "host": "api.yourdomain.com", "path": "/health" },
    { "host": "api.yourdomain.com", "path": "/metrics" }
  ],
  "masked_keywords": [
    "password", "pwd", "secret",
    "password_confirmation", "passwordConfirmation",
    "cc", "card_number", "cardNumber", "ccv",
    "credit_score", "creditScore", "ssn"
  ]
}

Configuration reference

Each object in exclude_routes:

Excluding routes

The agent monitors all JSON API traffic by default. A request is excluded only when its Host header matches an entry’s host field, and its URL path starts with the entry’s path prefix (if specified). All non-JSON responses (HTML, CSS, JS, images) are automatically ignored - no configuration needed.

The snippets below are example entries for the exclude_routes array in your config file. The // comments are only there to explain each one - leave them out of the real file.

// Exclude an entire internal host
{ "host": "internal.yourdomain.com" }
 
// Exclude health and metrics endpoints on a specific host
{ "host": "api.yourdomain.com", "path": "/health" },
{ "host": "api.yourdomain.com", "path": "/metrics" }
 
// Exclude a legacy API version
{ "host": "api.yourdomain.com", "path": "/v1" }

Sensitive data masking

The agent redacts field values matching masked_keywords before any data leaves the server. Masking applies to request bodies, response bodies, request headers, and response headers. Each character of a matched value is replaced with * so the length is preserved.

The following fields are masked by default when masked_keywords is omitted:

password, pwd, secret, password_confirmation, passwordConfirmation, cc, card_number, cardNumber, ccv, credit_score, creditScore, ssn

To add custom keywords, specify your full list (it replaces the defaults entirely):

"masked_keywords": [
  "password", "pwd", "secret",
  "password_confirmation", "passwordConfirmation",
  "cc", "card_number", "cardNumber", "ccv",
  "credit_score", "creditScore", "ssn",
  "api_token", "access_token", "private_key"
]

Updating the agent

Download the new TreblleAgent.dll from the Releases page, put it in the installer\ folder, and run the install script again - it handles re-registration automatically:

.\install.ps1

To update manually, stop IIS, replace the DLL with the newly downloaded one, then start IIS again:

iisreset /stop
Copy-Item path\to\new\TreblleAgent.dll C:\iismodules\treblle\TreblleAgent.dll
iisreset /start

Uninstalling

.\uninstall.ps1

This unregisters the agent from IIS and asks whether you also want to delete C:\iismodules\treblle\, which contains your treblle.config.

Debug mode

Set "debug": true in treblle.config to write errors to the Windows Application Event Log under source Treblle. Open Event Viewer → Windows Logs → Application and filter by source Treblle.

Common log entries:

Troubleshooting

Agent doesn’t appear in appcmd list module

• Confirm you ran the installer as Administrator
• Look in Event Viewer → Windows Logs → System for IIS startup errors
• Confirm you downloaded the x64 release DLL (the agent does not run on x86)

Agent is registered but no data appears in Treblle

1. Confirm the API returns Content-Type: application/json in the response
2. Check that the host/path is not matched by an exclude_routes entry
3. Enable "debug": true and check the Application Event Log
4. Verify network access from the server to ingress.treblle.com:443

IIS fails to start after installing the agent

• Confirm the DLL path in C:\Windows\System32\inetsrv\config\applicationHost.config matches the actual file location
• Temporarily rename TreblleAgent.dll and restart IIS to confirm it is the cause
• Grant app-pool read permissions as described in Step 3 above

Request bodies are empty in Treblle

• Confirm the request includes Content-Type: application/json
• Bodies larger than 2 MB are intentionally not captured