frameassembly 1.4.1

Offline, rootless PCAP generator & Packets-as-Code DSL: generate deterministic .pcap/.pcapng from text across 81 protocols for Wireshark, tcpreplay & IDS.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271

//! Simple Network Management Protocol v1, v2c, and v3 (SNMP, RFC 1157 / RFC 3416 / RFC 3414) AST definitions.
//!
//! This module defines the Abstract Syntax Tree (AST) types for SNMPv1 ([`Snmp1Spec`], RFC 1157),
//! community-based SNMPv2c ([`Snmp2Spec`], RFC 1901 / RFC 3416), and User-Based Security Model
//! SNMPv3 ([`Snmp3Spec`], RFC 3412 / RFC 3414 / RFC 3826 / RFC 7860) over UDP ports 161 (queries)
//! and 162 (traps/informs). On the wire, SNMP messages are ASN.1 BER `SEQUENCE` envelopes carrying
//! version integers (`0`, `1`, `3`), community or USM security parameters (HMAC-MD5/SHA/SHA-2 and
//! DES/AES-128 privacy), a context-tagged PDU (`GetRequest`, `GetNextRequest`, `Response`,
//! `SetRequest`, `Trap`, `GetBulkRequest`, `InformRequest`), and a sequence of [`VarBindAst`] pairs.

use alloc::vec::Vec;
use core::net::IpAddr;

/// Represents the ASN.1 BER PDU type of an SNMPv1, SNMPv2c, or SNMPv3 message.
#[doc(alias = "TRAP")]
#[doc(alias = "GET")]
#[doc(alias = "SET")]
#[doc(alias = "RESPONSE")]
#[doc(alias = "INFORM")]
#[doc(alias = "GETNEXT")]
#[doc(alias = "GETBULK")]
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum SnmpPduType {
    /// SNMPv1 Trap (`0xA4`) or SNMPv2c/v3 Trapv2 (`0xA7`) PDU (`TRAP`).
    Trap,
    /// SNMP GetRequest (`0xA0`) PDU (`GET`).
    Get,
    /// SNMP SetRequest (`0xA3`) PDU (`SET`).
    Set,
    /// SNMP GetResponse (`0xA2`) PDU (`RESPONSE`).
    Response,
    /// SNMPv2c/v3 InformRequest (`0xA6`) PDU (`INFORM`).
    Inform,
    /// SNMP GetNextRequest (`0xA1`) PDU (`GETNEXT`).
    GetNext,
    /// SNMPv2c/v3 GetBulkRequest (`0xA5`) PDU (`GETBULK`).
    GetBulk,
}

/// Represents the SNMPv3 User-Based Security Model (USM) authentication algorithm (RFC 3414 / RFC 7860).
#[doc(alias = "AUTH")]
#[doc(alias = "MD5")]
#[doc(alias = "SHA")]
#[doc(alias = "SHA256")]
#[doc(alias = "SHA384")]
#[doc(alias = "SHA512")]
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum SnmpAuthType {
    /// HMAC-MD5-96 authentication (`AUTH MD5 <pass>`, RFC 3414).
    Md5,
    /// HMAC-SHA-96 authentication (`AUTH SHA <pass>`, RFC 3414).
    Sha,
    /// HMAC-SHA-256-128 authentication (`AUTH SHA256 <pass>`, RFC 7860).
    Sha256,
    /// HMAC-SHA-384-192 authentication (`AUTH SHA384 <pass>`, RFC 7860).
    Sha384,
    /// HMAC-SHA-512-256 authentication (`AUTH SHA512 <pass>`, RFC 7860).
    Sha512,
}

/// Represents the SNMPv3 User-Based Security Model (USM) privacy encryption algorithm (RFC 3414 / RFC 3826).
#[doc(alias = "PRIV")]
#[doc(alias = "DES")]
#[doc(alias = "AES")]
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum SnmpPrivType {
    /// CBC-DES 56-bit privacy (`PRIV DES <pass>`, RFC 3414).
    Des,
    /// CFB128-AES-128 privacy (`PRIV AES <pass>`, RFC 3826).
    Aes,
}

/// Represents the typed SMIv1/SMIv2 value of an SNMP variable binding (`VARBIND <oid> <type> [val]`).
#[doc(alias = "VARBIND")]
#[doc(alias = "NULLVAL")]
#[doc(alias = "STRING")]
#[doc(alias = "INT")]
#[doc(alias = "TIMETICKS")]
#[doc(alias = "IPVAL")]
#[doc(alias = "OIDVAL")]
#[doc(alias = "COUNTER32")]
#[doc(alias = "GAUGE32")]
#[doc(alias = "COUNTER64")]
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum VarBindType<'a> {
    /// ASN.1 `NULL` (`0x05`) value (`NULLVAL`).
    Null,
    /// ASN.1 `OCTET STRING` (`0x04`) value (`STRING <str>`).
    String(&'a str),
    /// ASN.1 32-bit signed `INTEGER` (`0x02`) value (`INT <i32>`).
    Int(i32),
    /// SMI `TimeTicks` (`0x43`) hundredths of a second value (`TIMETICKS <u32>`).
    TimeTicks(u32),
    /// SMI `IpAddress` (`0x40`) or RFC 4001 `InetAddress` value (`IPVAL <ip>`).
    Ip(IpAddr),
    /// ASN.1 `OBJECT IDENTIFIER` (`0x06`) value (`OIDVAL <oid>`).
    OidVal(&'a str),
    /// SMI `Counter32` (`0x41`) 32-bit wrapping counter (`COUNTER32 <u32>`).
    Counter32(u32),
    /// SMI `Gauge32` (`0x42`) 32-bit non-wrapping gauge (`GAUGE32 <u32>`).
    Gauge32(u32),
    /// SMIv2 `Counter64` (`0x46`) 64-bit high-capacity counter (`COUNTER64 <u64>`).
    Counter64(u64),
}

/// Represents a single SNMP variable binding (`VARBIND <oid> <type> [val]`).
///
/// Syntax mapping: `VARBIND <oid> <NULLVAL | STRING <str> | INT <i32> | TIMETICKS <u32> | IPVAL <ip> | OIDVAL <oid> | COUNTER32 <u32> | GAUGE32 <u32> | COUNTER64 <u64>>`
#[doc(alias = "VARBIND")]
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct VarBindAst<'a> {
    /// Dotted-decimal Object Identifier string (`<oid>`).
    pub oid: &'a str,
    /// Typed SMI value associated with the OID.
    pub val: VarBindType<'a>,
}

/// RFC 1157 Simple Network Management Protocol Version 1 (SNMPv1) specification.
///
/// Syntax mapping: `SNMP1 [TRAP | GET | GETNEXT | SET | RESPONSE] [COMMUNITY <str>] [ENTERPRISE <oid>] [AGENTIP <ip>] [GENTRAP <u32>] [SPECTRAP <u32>] [SYSUPTIME <u32>] [REQID <u32>] [VARBIND <oid> <val>...]`
#[doc(alias = "SNMP1")]
#[doc(alias = "RFC 1157")]
#[doc(alias = "RFC1157")]
#[doc(alias = "TRAP")]
#[doc(alias = "GET")]
#[doc(alias = "GETNEXT")]
#[doc(alias = "SET")]
#[doc(alias = "RESPONSE")]
#[doc(alias = "COMMUNITY")]
#[doc(alias = "ENTERPRISE")]
#[doc(alias = "AGENTIP")]
#[doc(alias = "GENTRAP")]
#[doc(alias = "SPECTRAP")]
#[doc(alias = "SYSUPTIME")]
#[doc(alias = "REQID")]
#[doc(alias = "VARBIND")]
#[derive(Debug, Clone, PartialEq, Eq, Default)]
pub struct Snmp1Spec<'a> {
    /// Cleartext SNMPv1 community string (`COMMUNITY <str>`, default `"public"`).
    pub community: Option<&'a str>,
    /// Enterprise OID for Trap-PDU (`ENTERPRISE <oid>`).
    pub enterprise: Option<&'a str>,
    /// Agent network address override for Trap-PDU (`AGENTIP <ip>`).
    pub agent_ip: Option<IpAddr>,
    /// Generic trap code `0..=6` (`GENTRAP <u32>`, default `6` for `enterpriseSpecific`).
    pub gen_trap: Option<u32>,
    /// Enterprise-specific trap sub-code (`SPECTRAP <u32>`, default `1`).
    pub spec_trap: Option<u32>,
    /// Agent `sysUpTime` in hundredths of a second (`SYSUPTIME <u32>`).
    pub sys_up_time: Option<u32>,
    /// Ordered list of SMIv1 variable bindings (`VARBIND <oid> <val>`).
    pub varbinds: Vec<VarBindAst<'a>>,
    /// SNMPv1 PDU operation type (`TRAP`, `GET`, `GETNEXT`, `SET`, `RESPONSE`).
    pub pdu_type: Option<SnmpPduType>,
}

/// RFC 1901 / RFC 3416 Community-Based Simple Network Management Protocol Version 2 (SNMPv2c) specification.
///
/// Syntax mapping: `SNMP2 [TRAP | INFORM | GET | GETNEXT | GETBULK | SET | RESPONSE] [COMMUNITY <str>] [REQID <u32>] [NONREPEATERS <u32>] [MAXREPETITIONS <u32>] [SYSUPTIME <u32>] [OID <oid>] [VARBIND <oid> <val>...]`
#[doc(alias = "SNMP2")]
#[doc(alias = "SNMPv2c")]
#[doc(alias = "RFC 3416")]
#[doc(alias = "RFC3416")]
#[doc(alias = "RFC 1901")]
#[doc(alias = "RFC1901")]
#[doc(alias = "TRAP")]
#[doc(alias = "INFORM")]
#[doc(alias = "GET")]
#[doc(alias = "GETNEXT")]
#[doc(alias = "GETBULK")]
#[doc(alias = "SET")]
#[doc(alias = "RESPONSE")]
#[doc(alias = "COMMUNITY")]
#[doc(alias = "REQID")]
#[doc(alias = "NONREPEATERS")]
#[doc(alias = "MAXREPETITIONS")]
#[doc(alias = "SYSUPTIME")]
#[doc(alias = "OID")]
#[doc(alias = "VARBIND")]
#[derive(Debug, Clone, PartialEq, Eq, Default)]
pub struct Snmp2Spec<'a> {
    /// Cleartext SNMPv2c community string (`COMMUNITY <str>`, default `"public"`).
    pub community: Option<&'a str>,
    /// Ordered list of SMIv2 variable bindings (`VARBIND <oid> <val>`).
    pub varbinds: Vec<VarBindAst<'a>>,
    /// SNMPv2c PDU operation type (`TRAP`, `INFORM`, `GET`, `GETNEXT`, `GETBULK`, `SET`, `RESPONSE`).
    pub pdu_type: Option<SnmpPduType>,
    /// `non-repeaters` count for `GetBulkRequest` (`NONREPEATERS <u32>`).
    pub non_repeaters: Option<u32>,
    /// `max-repetitions` count for `GetBulkRequest` (`MAXREPETITIONS <u32>`).
    pub max_repetitions: Option<u32>,
    /// 32-bit PDU `request-id` (`REQID <u32>`).
    pub req_id: Option<u32>,
}

/// RFC 3412 / RFC 3414 Simple Network Management Protocol Version 3 (SNMPv3 USM) specification.
///
/// Syntax mapping: `SNMP3 [TRAP | INFORM | GET | GETNEXT | GETBULK | SET | RESPONSE] [USER <str>] [ENGINEID <hex>] [ENGINEBOOTS <u32>] [ENGINETIME <u32>] [CONTEXTNAME <str>] [AUTH <alg> <pass>] [PRIV <alg> <pass>] [REQID <u32>] [NONREPEATERS <u32>] [MAXREPETITIONS <u32>] [SYSUPTIME <u32>] [OID <oid>] [VARBIND <oid> <val>...]`
#[doc(alias = "SNMP3")]
#[doc(alias = "SNMPv3")]
#[doc(alias = "RFC 3414")]
#[doc(alias = "RFC3414")]
#[doc(alias = "RFC 3412")]
#[doc(alias = "RFC 3826")]
#[doc(alias = "RFC 7860")]
#[doc(alias = "TRAP")]
#[doc(alias = "INFORM")]
#[doc(alias = "GET")]
#[doc(alias = "GETNEXT")]
#[doc(alias = "GETBULK")]
#[doc(alias = "SET")]
#[doc(alias = "RESPONSE")]
#[doc(alias = "USER")]
#[doc(alias = "ENGINEID")]
#[doc(alias = "ENGINEBOOTS")]
#[doc(alias = "ENGINETIME")]
#[doc(alias = "CONTEXTNAME")]
#[doc(alias = "AUTH")]
#[doc(alias = "PRIV")]
#[doc(alias = "REQID")]
#[doc(alias = "NONREPEATERS")]
#[doc(alias = "MAXREPETITIONS")]
#[doc(alias = "SYSUPTIME")]
#[doc(alias = "OID")]
#[doc(alias = "VARBIND")]
#[derive(Debug, Clone, PartialEq, Eq, Default)]
pub struct Snmp3Spec<'a> {
    /// USM securityName (`USER <str>`, default `"admin"`).
    pub user: Option<&'a str>,
    /// Hex-encoded `msgAuthoritativeEngineID` (`ENGINEID <hex>`).
    pub engine_id: Option<&'a str>,
    /// `msgAuthoritativeEngineBoots` counter (`ENGINEBOOTS <u32>`, default `1`).
    pub engine_boots: Option<u32>,
    /// `msgAuthoritativeEngineTime` in seconds (`ENGINETIME <u32>`, default `100`).
    pub engine_time: Option<u32>,
    /// ScopedPDU `contextName` (`CONTEXTNAME <str>`, default `""`).
    pub context_name: Option<&'a str>,
    /// USM authentication algorithm and passphrase (`AUTH <MD5|SHA|SHA256|SHA384|SHA512> <pass>`).
    pub auth: Option<(SnmpAuthType, &'a str)>,
    /// USM privacy algorithm and passphrase (`PRIV <DES|AES> <pass>`).
    pub priv_param: Option<(SnmpPrivType, &'a str)>,
    /// Ordered list of SMIv2 variable bindings (`VARBIND <oid> <val>`).
    pub varbinds: Vec<VarBindAst<'a>>,
    /// SNMPv3 ScopedPDU operation type (`TRAP`, `INFORM`, `GET`, `GETNEXT`, `GETBULK`, `SET`, `RESPONSE`).
    pub pdu_type: Option<SnmpPduType>,
    /// `non-repeaters` count for `GetBulkRequest` (`NONREPEATERS <u32>`).
    pub non_repeaters: Option<u32>,
    /// `max-repetitions` count for `GetBulkRequest` (`MAXREPETITIONS <u32>`).
    pub max_repetitions: Option<u32>,
    /// 32-bit PDU `request-id` (`REQID <u32>`).
    pub req_id: Option<u32>,
}

/// Type alias for SNMP variable binding ([`VarBindAst`]).
pub type SnmpVarBind<'a> = VarBindAst<'a>;

/// Type alias for SNMP variable binding value ([`VarBindType`]).
pub type SnmpValue<'a> = VarBindType<'a>;

/// Type alias for SNMP authentication protocol ([`SnmpAuthType`]).
pub type SnmpAuthProtocol = SnmpAuthType;

/// Type alias for SNMP privacy protocol ([`SnmpPrivType`]).
pub type SnmpPrivProtocol = SnmpPrivType;

/// SNMP security model identifier (RFC 3411 / RFC 3414).
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum SnmpSecurityModel {
    /// User-Based Security Model (USM, securityModel 3, RFC 3414).
    Usm,
}