base_msg.proto

//
// Copyright 2020 Brightgate Inc.
//
// This Source Code Form is subject to the terms of the Mozilla Public
// License, v. 2.0. If a copy of the MPL was not distributed with this
// file, You can obtain one at https://mozilla.org/MPL/2.0/.
//

// vim:set comments=b\://:

// # Field number partitioning
//
// We write field numbers as hexadecimal integer literals, so that the
// partitioning is evident.  So that we might combine the messages into
// a smaller set of unified messages in the future, we partition the
// per-message field numbers into ranges.  (This choice trades off
// message size against later refactoring.) When adding a new message type,
// take the range roughly 100 above the message above.
//
// ## Common field numbers
//
// 0x01  Timestamp for event/message.
// 0x02  Sender string for event/message.
// ...
// 0x0f
//
// # Conventions
// - MAC addresses are the low 6 bytes of a 64-bit fixed integer.
// - IPv4 addresses are a 32-bit fixed integer.

// XXX Debian parser of the moment only recognizes "proto2".  Plan on an
// update.
syntax = "proto2";

package base_msg;

message Timestamp {
	required int64 seconds = 0x01;
	required int32 nanos = 0x02;
}

message Version {
	required int32 major = 0x01;
	optional int32 minor = 0x02;
}

// XXX In some ways, this enum duplicates content we already have in
// services(5).  But since services mixes TCP, UDP, and RPC with a
// syntax beyond an integer, we will build our own list for now.
enum Protocol {
	DNS = 1;
	DHCP = 2;
	IP = 3;
}

// The ping message is sent shortly after an application or service
// establishes its publication connection to the broker.  It should be the
// first message sent after connection establishment.
// @topic "sys.ping", TOPIC_PING
// @range 0x100
message EventPing {
	required Timestamp timestamp = 0x01;
	optional string sender = 0x02;
	optional string debug = 0x03;

	optional string ping_message = 0x100;
}

// MCPRequest messages are used by child daemons to send status updates to mcp,
// and by ap-ctl to send commands and query status.
// @range 0x140
message MCPRequest {
	required Timestamp timestamp = 0x01;
	optional string sender = 0x02;
	optional string debug = 0x03;
	required Version version = 0x05;

	enum Operation {
		PING = 1;
		GET = 2;
		SET = 3;
		DO = 4;
		UPDATE = 5;
		REBOOT = 6;
		GATEWAY = 7;
	}
	required Operation operation = 0x140;

	optional string state = 0x141;
	optional string command = 0x142;
	optional string daemon = 0x143;
	optional string node = 0x144;
	optional int32 lifetime = 0x145;
}

// MCPResponse messages are sent by ap.mcp in response to MCPRequest messages
// @range 0x180
message MCPResponse {
	required Timestamp timestamp = 0x01;
	optional string sender = 0x02;
	optional string debug = 0x03;
	required Version version = 0x05;
	optional Version min_version = 0x06;

	enum OpResponse {
		OP_OK = 0;
		BADVERSION = 1;
		NO_DAEMON = 2;
		INVALID = 99;
	}
	required OpResponse response = 0x180;

	optional string state = 0x181;
}

// The config message is sent whenever an application or service
// modifies shared configuration.  Subscribers--all applications or
// services that have public configuration--must then determine whether or
// not they must modify their operations in response to the updated
// configuration.
// @topic "sys.config", TOPIC_CONFIG
// @range 0x200
message EventConfig {
	required Timestamp timestamp = 0x01;
	optional string sender = 0x02;
	optional string debug = 0x03;

	enum Type {
		CHANGE = 1;
		DELETE = 2;
		EXPIRE = 3;
	}

	optional Type type = 0x200;
	optional string property = 0x202;
	optional string new_value = 0x203;
	optional Timestamp expires = 0x204;
	optional bytes hash = 0x205;
}

// The system error message is sent whenever an appliance service
// encounters a surprising failure.
// @topic "sys.error", TOPIC_ERROR
// @range 0x300
message EventSysError {
	required Timestamp timestamp = 0x01;
	optional string sender = 0x02;
	optional string debug = 0x03;
	optional string identity_uuid = 0x04;

	enum Cause {
		RENEWED_SSL_CERTIFICATE = 1;
		DAEMON_CRASH_REQUESTED = 2;
		VPN_KEY_MISMATCH = 3;
	}
	optional Cause reason = 0x341;
	optional string message = 0x342;
}


// The network entity message is sent whenever an application or service
// suspects that it has discovered a new or modified entity (IP endpoint)
// on a network, or when it believes that an entity has departed the
// network.
// @topic "net.entity", TOPIC_ENTITY
// @range 0x400
message EventNetEntity {
	required Timestamp timestamp = 0x01;
	optional string sender = 0x02;
	optional string debug = 0x03;

	optional fixed64 mac_address = 0x400;
	optional fixed32 ipv4_address = 0x401;
	optional string ring = 0x402;
	optional string hostname = 0x403;
	optional string node = 0x404;
	optional string band = 0x405; // e.g. 2.4GHz, 5GHz
	optional string virtualAP = 0x406;
	optional string wifi_signature = 0x407;
	optional bool disconnect = 0x408;
	optional string username = 0x409;
}

// The network resource is sent whenever an application or service
// allocates or reclaims a resource it manages.  An example managed
// resource would be DHCP lease offers and releases.
// @topic "net.resource", TOPIC_RESOURCE
// @range 0x500
message EventNetResource {
	required Timestamp timestamp = 0x01;
	optional string sender = 0x02;
	optional string debug = 0x03;

	enum Action {
		RELEASED = 1;
		PROVISIONED = 2;
		CLAIMED = 3;
		COLLISION = 4;
	}

	optional Action action = 0x500;
	optional fixed32 ipv4_address = 0x501;
	optional string hostname = 0x502;
	optional fixed32 duration = 0x503;
	// Who's involved?
}

// The network request is sent whenever an application or service issues
// an information request that does not imply allocation.  An example
// request would be a DNS host lookup.
//
// For DNS, the requestor field is an IP address.  There may be multiple
// requests and responses.
//
// For DHCP, the requestor field is a MAC address.  There is typically
// one request and one response.
//
// @topic "net.request", TOPIC_REQUEST
// @range 0x600
message EventNetRequest {
	required Timestamp timestamp = 0x01;
	optional string sender = 0x02;
	optional string debug = 0x03;
	optional string identity_uuid = 0x04;

	optional Protocol protocol = 0x0600;

	repeated string request = 0x0601;
	repeated string response = 0x0602;

	// protocol-specific requestor
	optional string requestor = 0x0603;
}

// XXX net.service
// @topic "net.service", TOPIC_SERVICE
// @range 0x700

// The network exception is sent whenever an application or service
// detects a request that is not allowed and responds with the reason
// for the disallowance.
// @topic "net.exception", TOPIC_EXCEPTION
// @range 0x800

message EventNetException {
	required Timestamp timestamp = 0x01;
	optional string sender = 0x02;
	optional string debug = 0x03;
	optional string identity_uuid = 0x04;

	optional Protocol protocol = 0x0800;

	enum Reason {
		PHISHING_ADDRESS	= 1;
		BLOCKED_IP		= 2;
		VULNERABILITY_DETECTED	= 3;
		BAD_PASSWORD		= 4;
		BAD_RING		= 5;
		CLIENT_RETRANSMIT	= 6;
		TEST_EXCEPTION          = 7; // For integration testing
	}
	optional Reason reason		= 0x801;
	optional string message		= 0x802;
	optional fixed64 mac_address	= 0x803;
	optional fixed32 ipv4_address	= 0x804;
	optional string virtualAP	= 0x805;
	repeated string details		= 0x806;
	optional string username	= 0x807;
}

// Contains notification that new device inventory records are ready
// for upload to cloud.
// @topic "net.device_inventory", TOPIC_DEVICE_INVENTORY
message EventDeviceInventory {
	required Timestamp timestamp = 0x01;
	optional string sender = 0x02;
	optional string debug = 0x03;
}


// The network updated event message is sent whenever the set of active network
// interfaces changes.
//
// @topic "net.update", TOPIC_UPDATE
message EventNetUpdate {
	required Timestamp timestamp = 0x01;
	optional string sender = 0x02;
	optional string debug = 0x03;
}

// The network public log message is sent whenever an application or service
// encounters a condition that has been documented as part of the
// public log message catalog.  The names for the specific fields are
// derived from the ArcSight CEF conventional names for that data, when
// included in a particular message.
//
// Common Event Format V25 has been our source for the conventional
// names.
//
// @topic "net.public_log", TOPIC_PUBLIC_LOG
// @range 0x900

message EventNetPublicLog {
	required Timestamp timestamp = 0x01;
	optional string sender = 0x02;
	optional string debug = 0x03;
	optional string identity_uuid = 0x04;

        optional string event_class_id = 0x900;

	optional string cef_act = 0x901;    // Used for Action (Quartine, Cleaned, Deleted, …) in an Anti-Virus context.
	optional string cef_app = 0x902;
	optional string cef_cat = 0x903;

	optional fixed64 cef_cn1 = 0x910;  // Used for Channel in a Wireless context.
	optional string cef_cn1Label = 0x911;

	optional string cef_cs1 = 0x920;    // Used for Rule Num in a // Firewall context.  // Used for Virus Name is an // Anti-Virus context.  // Used for Relay in an Email context.
	optional string cef_cs1Label = 0x921;
	optional string cef_cs2 = 0x922;    // Used for SSID in a Wireless context.  // Used for Signature in an Anti-Virus context.
	optional string cef_cs2Label = 0x923;

	optional string cef_dhost = 0x930;
	optional string cef_dmac = 0x931;
	optional uint32 cef_dpt = 0x932;
	optional string cef_dst = 0x933;
	optional string cef_duser = 0x934;	// Used for Recipient in an Email context.

	optional string cef_msg = 0x940;
	optional string cef_proto = 0x941;
	optional string cef_reason = 0x942;

	optional string cef_shost = 0x950;
	optional string cef_smac = 0x951;
	optional uint32 cef_spt = 0x952;
	optional string cef_src = 0x953;
	optional string cef_suser = 0x954;	// Used for Sender in an Email context.
}

// For network scans
message Port {
	required string protocol = 0x01;
	required int32 port_id = 0x02;
	required string state = 0x03;
	required string state_reason = 0x04;
	required string service_name = 0x05;
	required string service_method = 0x06;
	required int32 confidence = 0x07;
	optional string device_type = 0x08;
	optional string product = 0x09;
	optional string extra_info = 0x0a;
	optional string service_fp = 0x0b;
	optional string version = 0x0c;
	repeated string cpes = 0x0d;
	optional string ostype = 0x0e;
}

// Info for closed|filtered ports
message ExtraPort {
	required string state = 0x01;
	required int32 count = 0x02;
	required string reason = 0x03;
}

// used in OS identification
message UsedPort {
	required string state = 0x01;
	required string protocol = 0x02;
	required int32 port_id = 0x03;
}

message OSMatch {
	required string name = 0x01;
	required string accuracy = 0x02;
	required string line = 0x03;
	repeated OSClass os_classes = 0x04;
}

message OSClass {
	required string type = 0x01;
	required string vendor = 0x02;
	required string osfamily = 0x03;
	required string osgen = 0x04;
	required string accuracy = 0x05;
	repeated string cpes = 0x06;
}

// used for hostnames and addresses
message InfoAndType {
	required string info = 0x01;
	required string type = 0x02;
}

enum ScanType {
	UNKNOWN = 0;
	TCP_PORTS = 1;
	UDP_PORTS = 2;
	VULN = 3;
	PASSWD = 4;
	SUBNET = 5;
}

message Host {
	required Timestamp starttime = 0x01;
	required Timestamp endtime = 0x02;
	required string status = 0x03;
	required string status_reason = 0x04;
	repeated InfoAndType addresses = 0x05;
	repeated InfoAndType hostnames = 0x06;
	repeated ExtraPort extra_ports = 0x07;
	repeated Port ports = 0x08;

	repeated UsedPort ports_used = 0x09;
	repeated OSMatch os_matches = 0x0a;
	repeated string os_fingerprints = 0x0b;

	optional int32 uptime = 0x0c;
	optional string lastboot = 0x0d;
}

// Contains information about newest network scan
// @topic "net.scan", TOPIC_SCAN
// @range 0x1000
message EventNetScan {
	required Timestamp timestamp = 0x01;
	optional string sender = 0x02;
	optional string debug = 0x03;
	optional fixed32 ipv4_address = 0x04;
	optional string start_info = 0x1000;
	optional Timestamp start_time = 0x1001;
	optional Timestamp finish_time = 0x1002;
	repeated Host hosts = 0x1003;
	required string summary = 0x1004;
	optional ScanType scan_type = 0x1005;
}

message Pair {
	required string header = 0x01;
	required string value = 0x02;
}

// Contains information about SSDP
message EventSSDP {
	enum MessageType {
		ALIVE = 0;
		BYEBYE = 1;
		DISCOVER = 2;
	}
	required MessageType type = 0xb00;

	// notify and response
	optional string server = 0xb01;
	optional string unique_service_name = 0xb02;
	optional string location = 0xb03;

	// search and response
	optional string search_target = 0xb04;

	// notify
	optional string notification_type = 0xb05;

	repeated Pair extra_headers = 0xb0;
}

// Contains information about mDNS
message EventmDNS {
	repeated string request = 0xc00;
	repeated string response = 0xc01;
}

// Union of EventSSDP and EventmDNS messages
// @topic "net.listen", TOPIC_LISTEN
message EventListen {
	required Timestamp timestamp = 0x01;
	optional string sender = 0x02;
	optional string debug = 0x03;
	optional fixed32 ipv4_address = 0x04;

	enum Type {
		SSDP = 1;
		mDNS = 2;
	}
	required Type type = 0xa00;

	// Only one of these will be set
	optional EventSSDP ssdp = 0xa01;
	optional EventmDNS mdns = 0xa02;
}

message WatchdScanInfo {
	enum ScanState {
		ACTIVE		= 1;
		SCHEDULED	= 2;
	}

	optional uint32 id		= 0x01;
	optional string ip		= 0x02;
	optional string mac		= 0x03;
	optional ScanType type		= 0x04;
	optional ScanState state	= 0x05;
	optional Timestamp when		= 0x06;
	optional uint32 period		= 0x07;
}

message WatchdRequest {
	enum Cmd {
		SCAN_LIST	= 1;
		SCAN_ADD	= 2;
		SCAN_DEL	= 3;
		SCAN_RESCHED	= 4;
	}

	required Timestamp timestamp	= 0x01;
	optional string sender		= 0x02;
	required Cmd cmd		= 0x03;
	optional WatchdScanInfo scan	= 0x04;
}

message WatchdResponse {
	required Timestamp timestamp	= 0x01;
	optional string errmsg		= 0x02;
	repeated WatchdScanInfo scans	= 0x03;
}

// Namer suggestion messages (0x3000 - 0x37ff)

message NameRequest {
	required Timestamp timestamp = 0x01;
	optional string sender = 0x02;
	optional string debug = 0x03;
	optional string identity_uuid = 0x04;
}

message NameResponse {
	required Timestamp timestamp = 0x01;
	optional string sender = 0x02;
	optional string debug = 0x03;
	optional string identity_uuid = 0x04;
}

// Device identification messages (0x3800 - 0x3fff)

message IdentifyRequest {
	required Timestamp timestamp = 0x01;
	optional string sender = 0x02;
	optional string debug = 0x03;
	optional string identity_uuid = 0x04;
}

message IdentifyResponse {
	required Timestamp timestamp = 0x01;
	optional string sender = 0x02;
	optional string debug = 0x03;
	optional string identity_uuid = 0x04;

	optional float certainty = 0x3100;
}

// Which DHCP options were used by the client
// @topic "net.options", TOPIC_OPTIONS
message DHCPOptions {
	required Timestamp timestamp = 0x01;
	optional string sender = 0x02;
	optional string debug = 0x03;

	optional fixed64 mac_address = 0x04;
	optional uint32 msg_type = 0x05;

	// DHCP Option 55: Parameter Request List
	optional bytes param_req_list = 0x06;

	// DHCP Option 60: Vendor Class Identifier
	optional bytes vendor_class_id = 0x07;
}

// DeviceInfo messages are used to collect interesting events about a specific
// client. These messages are serialized to disk and sent to the cloud.
message DeviceInfo {
	optional Timestamp created = 0x01;
	optional Timestamp updated = 0x02;
	optional fixed64 mac_address = 0x03;
	optional string dns_name = 0x04;
	optional string dhcp_name = 0x05;

	optional EventNetEntity entity = 0x4000;
	repeated EventNetScan scan = 0x4001;
	repeated EventNetRequest request = 0x4002;
	repeated EventListen listen = 0x4003;
	repeated DHCPOptions options = 0x4004;
}

message DeviceInventory {
	optional Timestamp timestamp = 0x01;
	repeated DeviceInfo devices = 0x02;
}