Download the PHP package projektmotor/ids-sensor-bundle without Composer

IdsSensorBundle

Intrusion detection sensors for Symfony applications. Captures security-relevant events, normalizes them into a fixed wire format, and ships them over HTTPS to a separately operated collector — without ever slowing down the application it watches.

The sensor runs inside the application it monitors. If that application is compromised, so is the sensor — which is why it may only ever POST to the collector's three ingest endpoints. No endpoint returns stored events, and there is no DELETE: an attacker inside the application can neither read nor erase what has already been sent.

What it produces

One event, exactly as the collector receives it:

Nothing is normalized during the request. Capturing happens under a hard budget of 1500 µs (5 ms p99 ceiling for all sensors combined); normalizing, redacting and shipping happen on kernel.terminate, after the response has left. See Request lifecycle.

What it detects — and what it does not

This table comes before the installation instructions on purpose. Anyone who installs the bundle and overlooks the business layer believes something is monitored that is not.

Kernel and security layers reliably detect failed attacks — scanning, brute force, denied authorizations, error bursts. They see failures because a failure leaves a trace in the framework: a 403, a 404, an exception.

Successful attacks that use the application as intended produce no signal there. An attacker with a valid session who sets a discount to 100 %, retrieves another customer's order for which no voter exists, or exports data in quantities no human needs, produces nothing but HTTP 200. No amount of tightening the kernel rules compensates for this. The only remedy is the business layer — and that requires application code.

Details: Observation layers.

Requirements

Installation

That is the whole install. Earlier versions needed a second package for the message broker; the sensor now talks to the collector over HTTPS and brings its own client.

Symfony Flex registers the bundle automatically. Without Flex, add it to config/bundles.php:

Minimal configuration

Three identifiers and the collector credentials are mandatory. The collector hands you all of them when you register:

sensor_id must differ per node. One sensor is one running installation; if replicas share the identifier they are indistinguishable, and a silent sensor goes unnoticed. In Kubernetes all replicas of a Deployment share a ConfigMap — take this one from a per-pod secret or the Downward API instead.

Then verify the installation:

A non-zero exit code means detection is ineffective. Run it in your deployment pipeline, and do not defuse it with || true — the whole point is that misconfiguration surfaces at deploy time rather than during the post-mortem of an incident.

Full reference: Configuration.

Capturing business events

The only layer that needs application code — and the only one that can see successful attacks. Implement one interface:

Then dispatch it the way you already dispatch domain events — the sensor listens on the decorated event_dispatcher, and your business code contains no reference to the IDS:

Two alternatives exist for code bases that do not dispatch domain events, or deployments that reject decorating the dispatcher: Business layer.

Runtime models

The sensor ships after the response has been sent. Whether network access is permitted at that point depends on the runtime:

Under mod_php, ids:sensor:spool:flush is mandatory. It is the only delivery path there. Without a cron entry or systemd timer, the sensor writes, nobody collects, and the spool fills up and discards. The same applies to ids:sensor:heartbeat.

Why this is not merely conservative, and what it costs: Delivery path.

Commands

Documentation

The doc/ directory explains every core concept, one document each, with a diagram per concept. Written in German.

The full specification of both bundles — including the collector, its database schema and the detection rules — is doc/concept/concept-v1.md.

Public API and versioning

Semantic versioning applies to:

• ProjektMotor\IdsSensor\Contract\* — the interfaces your application implements or injects
• the IdsSensorBundle class and all ids_sensor configuration keys
• the emitted JSON, versioned via schema_version

Everything else, including all service IDs, is @internal and may change in any version. The rule is readable from the directory layout and enforced by tests/Unit/ArchitectureTest.php: whatever lives under Contract/ is public, every other file carries @internal.

The wire format itself — field names, enums, value objects, frame — lives in its own package, projektmotor/ids-event-data (ProjektMotor\IdsEventData\*), and is versioned there, where semantic versioning covers the package in full. The collector side consumes the very same package; that is why it depends on nothing at all — not even on Symfony.

Changes are recorded in CHANGELOG.md.

Contributing

No local PHP installation required — everything runs through Docker:

How src/ is laid out and why — which namespace belongs to which section of the concept, and when its code runs — is documented in doc/concept/structure.md. Read it before moving anything: the layout carries six promises that ArchitectureTest enforces.

If the service wiring changes, the container fingerprint is the actual review artefact — it compares 14 configuration variants definition by definition:

Read the resulting diff. That, not the green test run, is the check.

License

MIT — see LICENSE.