Audit Trail

Every session and file-transfer event is recorded by the audit subsystem. Four audit sinks can run simultaneously — each captures the same events independently. Enable any combination to match your compliance and operational monitoring requirements.

Audit Sinks

All audit sinks are configured inside the <audit> element of sftp-server.xml. Each sink has an enabled attribute that can be toggled without removing the configuration block.

1. Log Sink

The log sink writes audit events to the SLF4J logger com.ivitechnologies.stylussftpserver.audit at INFO level. It is enabled by default and requires no additional configuration.

<log enabled="true"/>

To route audit log entries to a separate file, add a dedicated Log4j 2 appender in log4j2.xml that targets the com.ivitechnologies.stylussftpserver.audit logger:

<Logger name="com.ivitechnologies.stylussftpserver.audit"
        level="INFO" additivity="false">
    <AppenderRef ref="AuditFile"/>
</Logger>

2. JDBC Sink

The JDBC sink writes events asynchronously to the sftp_audit database table via a LinkedBlockingQueue with a configurable capacity (default 10,000). Events are batched for throughput. The table is auto-created on first start.

<jdbc enabled="true">
    <driver-class-name>org.h2.Driver</driver-class-name>
    <url>jdbc:h2:${STYLUS_SFTPSERVER_DATA}/db/sftpdb;AUTO_SERVER=TRUE</url>
    <username>sa</username>
    <password>secret</password>
    <max-pool-size>5</max-pool-size>
    <queue-capacity>10000</queue-capacity>
</jdbc>

3. Syslog Sink (RFC 5424 UDP)

The syslog sink sends fire-and-forget UDP packets to a central syslog collector such as Splunk, ELK, or QRadar. Overhead is near-zero (approximately 10 microseconds per event).

<syslog enabled="true">
    <host>siem.example.com</host>
    <port>514</port>
    <facility>LOCAL0</facility>
</syslog>

Each message follows RFC 5424 format with structured data in a [sss@0] SD element containing all audit record fields. Severity mapping:

• INFO (6) — successful operations (authentication, upload, download)
• WARNING (4) — failures and denied operations

4. Webhook Sink

The webhook sink sends fire-and-forget HTTP POST requests via the JDK HttpClient. You can configure multiple webhooks, each with its own URL, event filter, and output format.

<webhooks>
    <webhook enabled="true">
        <url>https://hooks.slack.com/services/T00/B00/xxx</url>
        <events>UPLOAD_COMPLETE, AUTH_FAILURE</events>
        <format>text</format>
        <template>SSS ${event}: ${filename} by ${username}</template>
    </webhook>
</webhooks>

Formats

Template Variables

HMAC Signing

To verify that webhook payloads originate from Stylus SFTP Server, configure a shared secret. The server computes an HMAC-SHA256 signature over the request body and sends it in the X-SSS-Signature HTTP header. The receiving endpoint can recompute the HMAC and compare.

<webhook enabled="true">
    <url>https://api.example.com/sftp-events</url>
    <events>UPLOAD_COMPLETE, DOWNLOAD_COMPLETE</events>
    <format>json</format>
    <secret>my-shared-secret</secret>
</webhook>

Event Types

The table below lists the protocol-triggered event types — authentication, transfer, session, MFA, quota. Admin-triggered events (org / group / folder mutations, license administration, auth-orchestrator diagnostics) also flow through the audit stream but are catalogued exhaustively in Appendix B, which stays authoritative as new events are added.

Audit Record Fields

Every audit event carries the same set of fields, regardless of which sink receives it:

sftp_audit Table Schema

When the JDBC sink is enabled, the sftp_audit table is auto-created on first start with the following schema:

CREATE TABLE sftp_audit (
    id          BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
    occurred_at TIMESTAMP      NOT NULL,
    event_type  VARCHAR(32)    NOT NULL,
    username    VARCHAR(255),
    remote_ip   VARCHAR(45),
    filename    VARCHAR(1000),
    bytes       BIGINT,
    success     SMALLINT       NOT NULL,
    detail      VARCHAR(2000),
    executed_by VARCHAR(255)
)

CREATE TABLE sftp_audit_to_organization (
    audit_id   BIGINT    NOT NULL,
    org_id     BIGINT    NOT NULL,
    created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
    CONSTRAINT pk_sftp_audit_to_organization PRIMARY KEY (audit_id, org_id),
    CONSTRAINT fk_sftp_audit_to_organization_org
        FOREIGN KEY (org_id) REFERENCES sftp_organizations (org_id) ON DELETE CASCADE
)

All timestamps are stored as UTC. The application supplies each occurred_at value as a UTC instant when the event is recorded, and the install-time service registration sets -Duser.timezone=UTC so the JVM agrees; the admin surfaces convert to the operator's local timezone at display time.

The sftp_audit_to_organization link table records which organizations are relevant to each event. A single event can be tagged with multiple organizations — a Force5-employed operator acting on Austin Energy's folder produces an event linked to both orgs, so the Audit view can surface it under either tenant's filter. Pre-identity-model rows have no links and surface only in unfiltered queries.