Audit Service Reference

Use this reference to look up audit service architecture, interface definitions, field descriptions, and reply codes for application integration.

Architecture

┌─────────────────┐       Unix Socket (gRPC)        ┌───────────────────────┐
│   Your App      │ ──────────────────────────────► │  Audit Trail Service  │
│  (container)    │  /var/run/devicemodel/          │                       │
│                 │       [events/]audit.sock       │  ┌───► Local Log      │
└─────────────────┘                                 │  │    /data/audit/log │
                                                    │  │                    │
                                                    │  └───► Syslog (opt.)  │
                                                    └───────────────────────┘

Socket paths

The audit service exposes its gRPC interface through a Unix domain socket.

IEDK version	Socket path
≥ 1.22 and < 1.28	/var/run/devicemodel/audit.sock
≥ 1.28	/var/run/devicemodel/events/audit.sock

Protocol buffer definition

syntax = "proto3";
package proto;

service AuditTrail {
    rpc SendAuditRecord (AuditRecord) returns (AuditRecordReply) {}
}

enum Result {
    START = 0;
    SUCCESS = 1;
    FAILURE = 2;
    REJECTED_BY_APPLICATION = 3;
    STOP = 4;
    LOSS = 5;
    RETURN = 6;
    ACTIVATED = 7;
    DEACTIVATED = 8;
}

enum ProtocolType {
    HTTP = 0;
    HTTPS = 1;
}

enum ReplyCode {
    OK = 0;
    UNKNOWN = 2;
    INVALID_ARGUMENT = 3;
    UNAVAILABLE = 14;
}

message SessionData {
    ProtocolType protocolType = 1;
    string userID = 2;
    string src = 3;
    string sessionID = 4;
}

message FunctionData {
    string fct = 1;
    string resource = 2;
    Result result = 3;
    string oldState = 4;
    string newState = 5;
}

message AuditRecord {
    int32 apiVersion = 1;
    int32 eventID = 2;
    string appName = 3;
    FunctionData functionData = 4;
    SessionData SessionData = 5;
    string message = 6;
}

message AuditRecordReply {
    ReplyCode code = 1;
    string status = 2;
}

gRPC field reference

gRPC field or type	Sub field	Data type	Description	Example value
apiVersion		int32	The audit trail gRPC interface version.	1
eventID		int32	The ID of the IE Security Event. For more information, see DI Security Events.	58
appName		string	The name of the application that sends the audit record.	edgesdk
functionData	fct	string	The function related to the security event. See the Audit Event List for available functions.	ie.device.software.app.logs.download
functionData	resource	string	The resource handled by the function, for example a file name or protection level.	filename.txt
functionData	result	enum	The result of the function execution. Available values are START, SUCCESS, FAILURE, REJECTED_BY_APPLICATION, STOP, LOSS, RETURN, ACTIVATED, and DEACTIVATED.	SUCCESS
SessionData	protocolType	enum	The protocol type. Available values are HTTP and HTTPS.	HTTPS
SessionData	userID	string	The operator user ID.	3625ab55-5b7e-4e70-ab6d-796329f0a915
SessionData	src	string	The IP address or MAC address of the remote client.	192.168.142.11
SessionData	sessionID	string	An identifier for the established and authenticated session.	abc123
message		string	A free-form message that provides information about the event.	User login successfully.

JSON example

{
  "apiVersion": 1,
  "eventID": 58,
  "appName": "my-edge-app",
  "functionData": {
    "fct": "ie.device.software.app.configuration.update",
    "resource": "config.json",
    "result": "SUCCESS"
  },
  "SessionData": {
    "userID": "user@example.com",
    "src": "192.168.1.100",
    "sessionID": ""
  },
  "message": "User updated app configuration"
}

Severity levels

The eventID determines the severity of an audit event.

Severity	Abbreviation	Value	Meaning
Emergency	EM	0	A panic condition that prevents continuation of operation.
Alert	A	1	A system condition that requires immediate attention.
Critical	C	2	A failure in a primary system that is usually non-recoverable.
Error	E	3	A correctable error, for example an authentication failure or resource issue.
Warning	W	4	An indication that an error will occur if no action is taken.
Notice	N	5	An unusual event that is not an error condition, for example a configuration change.
Informational	I	6	A normal operational message.
Debug	D	7	Reserved for debugging information.

gRPC reply codes

Code	Status	Meaning
0	OK	The event was accepted and stored successfully.
2	UNKNOWN	An internal server error occurred while the event was processed.
3	INVALID_ARGUMENT	The eventID or severity field is not valid.
14	UNAVAILABLE	The audit service is currently unavailable.

Related documentation

• Audit Service Integration — Step-by-step guidance for integrating your application.
• Audit Event (Operator Guide) — Audit event functions and operator settings.