> ## Documentation Index
> Fetch the complete documentation index at: https://envtrap.vercel.app/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Incident Reports & Auditing

> Understanding .envtrap-report.json, streaming JSONL audit events, and responsible vulnerability disclosure.

# Incident Reports & Auditing

`envtrap` provides comprehensive auditing and reporting capabilities to help security teams, developers, and compliance engines inspect credential exposure incidents.

***

## 1. End-of-Run Report (`.envtrap-report.json`)

When an application monitored by `envtrap` terminates, `envtrap` compiles all intercepted leak events and writes a structured JSON file named `.envtrap-report.json` in the current working directory.

### Report Structure

```json .envtrap-report.json theme={null}
[
  {
    "secretName": "STRIPE_SECRET_KEY",
    "source": "env",
    "channel": "network",
    "context": "Outbound HTTPS Request Audited:\n  Destination Host: attacker-c2.example.com\n  Request Line: POST /collect\n  Headers:\n    Authorization: Bearer [REDACTED: SHA256:56018fa5]",
    "sha256": "56018fa554859a6898d927a4d4681604a5531d0448ff61168f1c8a14b51a084c",
    "timestamp": 1788114544924
  }
]
```

### Field Definitions

| Field Name | Type | Description |
| :- | :- | :- |
| `secretName` | `string` | The environment variable key name (e.g. `DATABASE_URL`). |
| `source` | `"env" \| "file"` | Origin of the secret (`"env"` from shell environment, `"file"` from `.env`). |
| `channel` | `string` | The intercepted egress vector (`"network"`, `"dns"`, `"child_process"`, `"stdout"`, `"stderr"`). |
| `context` | `string` | A sanitized contextual snippet showing where the secret appeared. Raw secrets are replaced with truncated hashes. |
| `sha256` | `string` | The 64-character SHA-256 hex digest of the secret value for cross-system correlation. |
| `timestamp` | `number` | Unix epoch timestamp in milliseconds when the incident occurred. |

***

## 2. Streaming JSONL Event Logs (`--log-file`)

For long-running microservices, production servers, or SIEM pipelines (such as Datadog, Splunk, or Elastic), waiting for process exit is not practical.

Configure `logFile` in `envtrap.json` or pass `--log-file <path>` on the CLI:

```bash theme={null}
envtrap run --log-file /var/log/envtrap-events.jsonl node server.js
```

Each intercepted leak is immediately appended as a single newline-delimited JSON line:

```json theme={null}
{"timestamp":1788114544924,"channel":"network","secretName":"STRIPE_SECRET_KEY","sha256":"56018fa5...","action":"block"}
{"timestamp":1788114545100,"channel":"dns","secretName":"AWS_SECRET_ACCESS_KEY","sha256":"9e107d9d...","action":"warn"}
```

***

## 3. Vulnerability Reporting & Disclosure

If you discover a security vulnerability or bypass within `envtrap` itself:

<Warning>
  **Do not open a public GitHub issue.** Publicly reporting a security flaw exposes active users before a patch can be deployed.
</Warning>

### How to Disclose:

* **Email**: Send vulnerability details and minimal reproductions to:
  ```text theme={null}
  security@envtrap.dev
  ```
* **Include**:
  1. A clear description of the vulnerability.
  2. Minimal reproduction steps or proof-of-concept code.
  3. Affected `envtrap` versions.
  4. Suggested remediation if available.

### Disclosure Timeline:

* **Acknowledgment**: Within 24 hours.
* **Severity Assessment**: Within 72 hours.
* **Patch & CVE Assignment**: Within 14–30 days.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.