syslog2cef 0.3.3__tar.gz → 0.4.1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (55) hide show
  1. {syslog2cef-0.3.3 → syslog2cef-0.4.1}/PKG-INFO +109 -34
  2. syslog2cef-0.3.3/syslog2cef.egg-info/PKG-INFO → syslog2cef-0.4.1/README.md +99 -53
  3. {syslog2cef-0.3.3 → syslog2cef-0.4.1}/pyproject.toml +9 -3
  4. syslog2cef-0.3.3/README.md → syslog2cef-0.4.1/syslog2cef.egg-info/PKG-INFO +129 -31
  5. {syslog2cef-0.3.3 → syslog2cef-0.4.1}/syslog2cef.egg-info/SOURCES.txt +2 -0
  6. {syslog2cef-0.3.3 → syslog2cef-0.4.1}/syslogcef/__init__.py +6 -0
  7. syslog2cef-0.4.1/syslogcef/_version.py +12 -0
  8. {syslog2cef-0.3.3 → syslog2cef-0.4.1}/syslogcef/cef.py +27 -0
  9. {syslog2cef-0.3.3 → syslog2cef-0.4.1}/syslogcef/cli.py +29 -1
  10. {syslog2cef-0.3.3 → syslog2cef-0.4.1}/syslogcef/custom.py +6 -18
  11. {syslog2cef-0.3.3 → syslog2cef-0.4.1}/syslogcef/mappings/cisco_asa.json +1 -1
  12. {syslog2cef-0.3.3 → syslog2cef-0.4.1}/syslogcef/parsers.py +3 -13
  13. {syslog2cef-0.3.3 → syslog2cef-0.4.1}/syslogcef/utils.py +28 -2
  14. {syslog2cef-0.3.3 → syslog2cef-0.4.1}/tests/test_cef.py +44 -0
  15. {syslog2cef-0.3.3 → syslog2cef-0.4.1}/tests/test_cli.py +99 -0
  16. {syslog2cef-0.3.3 → syslog2cef-0.4.1}/tests/test_custom_parsers.py +18 -1
  17. {syslog2cef-0.3.3 → syslog2cef-0.4.1}/tests/test_parsers_extra.py +44 -0
  18. {syslog2cef-0.3.3 → syslog2cef-0.4.1}/LICENSE +0 -0
  19. {syslog2cef-0.3.3 → syslog2cef-0.4.1}/setup.cfg +0 -0
  20. {syslog2cef-0.3.3 → syslog2cef-0.4.1}/syslog2cef.egg-info/dependency_links.txt +0 -0
  21. {syslog2cef-0.3.3 → syslog2cef-0.4.1}/syslog2cef.egg-info/entry_points.txt +0 -0
  22. {syslog2cef-0.3.3 → syslog2cef-0.4.1}/syslog2cef.egg-info/requires.txt +0 -0
  23. {syslog2cef-0.3.3 → syslog2cef-0.4.1}/syslog2cef.egg-info/top_level.txt +0 -0
  24. {syslog2cef-0.3.3 → syslog2cef-0.4.1}/syslogcef/__main__.py +0 -0
  25. {syslog2cef-0.3.3 → syslog2cef-0.4.1}/syslogcef/adaptive.py +0 -0
  26. {syslog2cef-0.3.3 → syslog2cef-0.4.1}/syslogcef/api.py +0 -0
  27. {syslog2cef-0.3.3 → syslog2cef-0.4.1}/syslogcef/dictionary.json +0 -0
  28. {syslog2cef-0.3.3 → syslog2cef-0.4.1}/syslogcef/dictionary.py +0 -0
  29. {syslog2cef-0.3.3 → syslog2cef-0.4.1}/syslogcef/mappings/__init__.py +0 -0
  30. {syslog2cef-0.3.3 → syslog2cef-0.4.1}/syslogcef/mappings/cisco_ios.json +0 -0
  31. {syslog2cef-0.3.3 → syslog2cef-0.4.1}/syslogcef/mappings/f5.json +0 -0
  32. {syslog2cef-0.3.3 → syslog2cef-0.4.1}/syslogcef/mappings/fortinet.json +0 -0
  33. {syslog2cef-0.3.3 → syslog2cef-0.4.1}/syslogcef/mappings/linux.json +0 -0
  34. {syslog2cef-0.3.3 → syslog2cef-0.4.1}/syslogcef/mappings/sophos.json +0 -0
  35. {syslog2cef-0.3.3 → syslog2cef-0.4.1}/syslogcef/mappings/vmware.json +0 -0
  36. {syslog2cef-0.3.3 → syslog2cef-0.4.1}/syslogcef/net.py +0 -0
  37. {syslog2cef-0.3.3 → syslog2cef-0.4.1}/syslogcef/normalizer.py +0 -0
  38. {syslog2cef-0.3.3 → syslog2cef-0.4.1}/syslogcef/validation.py +0 -0
  39. {syslog2cef-0.3.3 → syslog2cef-0.4.1}/tests/test_adaptive.py +0 -0
  40. {syslog2cef-0.3.3 → syslog2cef-0.4.1}/tests/test_cli_validation.py +0 -0
  41. {syslog2cef-0.3.3 → syslog2cef-0.4.1}/tests/test_dictionary.py +0 -0
  42. {syslog2cef-0.3.3 → syslog2cef-0.4.1}/tests/test_fuzz_grammar.py +0 -0
  43. {syslog2cef-0.3.3 → syslog2cef-0.4.1}/tests/test_fuzz_properties.py +0 -0
  44. {syslog2cef-0.3.3 → syslog2cef-0.4.1}/tests/test_macos_logs.py +0 -0
  45. {syslog2cef-0.3.3 → syslog2cef-0.4.1}/tests/test_net.py +0 -0
  46. {syslog2cef-0.3.3 → syslog2cef-0.4.1}/tests/test_normalizer.py +0 -0
  47. {syslog2cef-0.3.3 → syslog2cef-0.4.1}/tests/test_parsers.py +0 -0
  48. {syslog2cef-0.3.3 → syslog2cef-0.4.1}/tests/test_pipeline.py +0 -0
  49. {syslog2cef-0.3.3 → syslog2cef-0.4.1}/tests/test_real_world.py +0 -0
  50. {syslog2cef-0.3.3 → syslog2cef-0.4.1}/tests/test_rfc5424_epoch.py +0 -0
  51. {syslog2cef-0.3.3 → syslog2cef-0.4.1}/tests/test_security_hardening.py +0 -0
  52. {syslog2cef-0.3.3 → syslog2cef-0.4.1}/tests/test_tail_rotation.py +0 -0
  53. {syslog2cef-0.3.3 → syslog2cef-0.4.1}/tests/test_utils.py +0 -0
  54. {syslog2cef-0.3.3 → syslog2cef-0.4.1}/tests/test_validation.py +0 -0
  55. {syslog2cef-0.3.3 → syslog2cef-0.4.1}/tests/test_zipapp_safe.py +0 -0
@@ -1,13 +1,19 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: syslog2cef
3
- Version: 0.3.3
3
+ Version: 0.4.1
4
4
  Summary: Convert RFC3164/RFC5424 syslog lines into ArcSight CEF
5
5
  Author-email: Tamir Suliman <allamiro@gmail.com>
6
- Project-URL: Homepage, https://github.com/allamiro/syslogcef
7
- Project-URL: Issues, https://github.com/allamiro/syslogcef/issues
6
+ Project-URL: Homepage, https://github.com/allamiro/syslog2cef
7
+ Project-URL: Issues, https://github.com/allamiro/syslog2cef/issues
8
8
  Keywords: syslog,cef,logging,security
9
9
  Classifier: Programming Language :: Python :: 3
10
10
  Classifier: Programming Language :: Python :: 3 :: Only
11
+ Classifier: Programming Language :: Python :: 3.9
12
+ Classifier: Programming Language :: Python :: 3.10
13
+ Classifier: Programming Language :: Python :: 3.11
14
+ Classifier: Programming Language :: Python :: 3.12
15
+ Classifier: Programming Language :: Python :: 3.13
16
+ Classifier: Programming Language :: Python :: 3.14
11
17
  Classifier: License :: OSI Approved :: MIT License
12
18
  Classifier: Topic :: System :: Logging
13
19
  Requires-Python: >=3.9
@@ -22,12 +28,25 @@ Requires-Dist: hypothesis>=6; extra == "fuzz"
22
28
  Dynamic: license-file
23
29
 
24
30
  <p align="center">
25
- <img src="https://raw.githubusercontent.com/allamiro/syslogcef/main/docs/logo.svg" alt="syslogcef logo" width="540">
31
+ <img src="https://raw.githubusercontent.com/allamiro/syslog2cef/main/docs/logo.svg" alt="syslog2cef logo" width="540">
26
32
  </p>
27
33
 
28
- # syslogcef
34
+ <p align="center">
35
+ <a href="https://github.com/allamiro/syslog2cef/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/allamiro/syslog2cef/ci.yml?branch=main&label=CI" alt="CI status"></a>
36
+ <a href="https://pypi.org/project/syslog2cef/"><img src="https://img.shields.io/pypi/v/syslog2cef" alt="PyPI version"></a>
37
+ <a href="https://pypi.org/project/syslog2cef/"><img src="https://img.shields.io/pypi/pyversions/syslog2cef" alt="Supported Python versions"></a>
38
+ <a href="https://pypistats.org/packages/syslog2cef"><img src="https://img.shields.io/pypi/dm/syslog2cef" alt="PyPI downloads per month"></a>
39
+ <a href="https://copr.fedorainfracloud.org/coprs/allamiro/syslogcef/"><img src="https://copr.fedorainfracloud.org/coprs/allamiro/syslogcef/package/syslogcef/status_image/last_build.png" alt="COPR build status"></a>
40
+ <a href="https://github.com/allamiro/syslog2cef/pkgs/container/syslog2cef"><img src="https://img.shields.io/badge/container-ghcr.io-blue?logo=docker" alt="Container image on ghcr.io"></a>
41
+ <a href="https://github.com/allamiro/syslog2cef/actions/workflows/fuzz.yml"><img src="https://img.shields.io/github/actions/workflow/status/allamiro/syslog2cef/fuzz.yml?branch=main&label=deep%20fuzz" alt="Deep fuzz status"></a>
42
+ <a href="https://github.com/astral-sh/ruff"><img src="https://img.shields.io/badge/lint-ruff-261230" alt="Linted with Ruff"></a>
43
+ <a href="LICENSE"><img src="https://img.shields.io/github/license/allamiro/syslog2cef" alt="MIT license"></a>
44
+ <a href="CITATION.cff"><img src="https://img.shields.io/badge/cite-CITATION.cff-informational" alt="Citation file"></a>
45
+ </p>
46
+
47
+ # syslog2cef
29
48
 
30
- syslogcef converts syslog events into ArcSight Common Event Format (CEF). It
49
+ syslog2cef converts syslog events into ArcSight Common Event Format (CEF). It
31
50
  is a small, dependency-free Python package with a command line interface,
32
51
  built for feeding syslog data from network devices and Linux hosts into SIEM
33
52
  platforms that consume CEF.
@@ -36,11 +55,18 @@ platforms that consume CEF.
36
55
 
37
56
  - Automatic detection and parsing of multiple syslog dialects:
38
57
  RFC3164 (BSD), RFC5424 (including structured data), rsyslog JSON and
39
- file formats, and systemd journal exports (JSON, short, and ISO formats).
58
+ file formats, systemd journal exports (JSON, short, and ISO formats),
59
+ Cisco console/buffer lines, ISO-timestamp syslog, and key=value streams
60
+ (Fortinet, Sophos). Unknown layouts are learned adaptively.
40
61
  - Deterministic vendor/product mappings bundled for Cisco ASA, Cisco IOS,
41
- F5 BIG-IP, generic Linux, and VMware ESXi, with automatic mapping
42
- selection based on message content.
43
- - Custom mappings supplied as JSON files or Python dictionaries.
62
+ F5 BIG-IP, Fortinet FortiGate, Sophos XG Firewall, VMware ESXi, and
63
+ generic Linux, with automatic mapping selection based on message content.
64
+ - Custom mappings supplied as JSON files or Python dictionaries, and custom
65
+ parsers supplied as regex pattern files.
66
+ - Validation of CEF extension values against the ArcSight extension
67
+ dictionary (`--validate`, `--strict`).
68
+ - Network receiver (`--listen udp:514`) and forwarding to UDP, TCP, or
69
+ Kafka (`--send`), with optional rate limiting.
44
70
  - Escaping of untrusted log content in both CEF header and extension
45
71
  fields, so crafted messages cannot forge header fields or split records.
46
72
  - Streaming CLI with stdin/file input, tail (follow) mode across multiple
@@ -50,19 +76,25 @@ platforms that consume CEF.
50
76
 
51
77
  ## Installation
52
78
 
53
- From PyPI (the distribution is named `syslog2cef` because the `syslogcef`
54
- name on PyPI belongs to an unrelated project; the import package and CLI
55
- are still `syslogcef`):
79
+ From PyPI:
56
80
 
57
81
  ```bash
58
82
  pip install syslog2cef
59
83
  ```
60
84
 
85
+ > **Naming.** The project, this repository, the PyPI distribution and the
86
+ > RPM/DEB/APK packages are all `syslog2cef`. The command you run and the
87
+ > Python package you import are `syslogcef`, unchanged — as are the config
88
+ > paths (`/etc/syslogcef/`), the systemd units and the log directory, so
89
+ > upgrading from an earlier release needs no changes. The `syslogcef` name
90
+ > on PyPI belongs to an unrelated project, which is why the distribution
91
+ > has always been `syslog2cef`.
92
+
61
93
  From source:
62
94
 
63
95
  ```bash
64
- git clone https://github.com/allamiro/syslogcef.git
65
- cd syslogcef
96
+ git clone https://github.com/allamiro/syslog2cef.git
97
+ cd syslog2cef
66
98
  pip install .
67
99
  ```
68
100
 
@@ -70,21 +102,21 @@ The GitHub releases page also provides, for every version:
70
102
 
71
103
  - An RPM package (Fedora/RHEL) with a systemd service — see "Running as a
72
104
  Service" below.
73
- - A Debian package (`syslogcef_X.Y.Z-1_all.deb`) with the same systemd
74
- service: `sudo apt install ./syslogcef_X.Y.Z-1_all.deb`.
105
+ - A Debian package (`syslog2cef_X.Y.Z-1_all.deb`) with the same systemd
106
+ service: `sudo apt install ./syslog2cef_X.Y.Z-1_all.deb`.
75
107
  - An Alpine APK with an OpenRC service:
76
- `apk add --allow-untrusted syslogcef-X.Y.Z-r0.apk` (or install the
108
+ `apk add --allow-untrusted syslog2cef-X.Y.Z-r0.apk` (or install the
77
109
  signing key from [packaging/apk/syslogcef.rsa.pub](packaging/apk/syslogcef.rsa.pub)
78
110
  into `/etc/apk/keys/` first to verify).
79
- - A standalone executable (`syslogcef-X.Y.Z.pyz`) that runs on any system
80
- with Python 3.9+: `chmod +x syslogcef-X.Y.Z.pyz && ./syslogcef-X.Y.Z.pyz`.
111
+ - A standalone executable (`syslog2cef-X.Y.Z.pyz`) that runs on any system
112
+ with Python 3.9+: `chmod +x syslog2cef-X.Y.Z.pyz && ./syslog2cef-X.Y.Z.pyz`.
81
113
  - A source zip and sdist/wheel files.
82
114
 
83
115
  A multi-arch (amd64/arm64) container image is published to GitHub
84
116
  Container Registry on each release:
85
117
 
86
118
  ```bash
87
- docker run -i ghcr.io/allamiro/syslogcef < /var/log/syslog
119
+ docker run -i ghcr.io/allamiro/syslog2cef < /var/log/syslog
88
120
  ```
89
121
 
90
122
  Fedora, RHEL/Alma/Rocky 9 and 10, and CentOS Stream users can install
@@ -93,9 +125,13 @@ which rebuilds automatically from every commit:
93
125
 
94
126
  ```bash
95
127
  sudo dnf copr enable allamiro/syslogcef
96
- sudo dnf install syslogcef
128
+ sudo dnf install syslog2cef
97
129
  ```
98
130
 
131
+ The COPR project keeps its original name (`allamiro/syslogcef`) so that
132
+ already-enabled repositories keep working; the package it builds is
133
+ `syslog2cef`.
134
+
99
135
  Every asset ships with a detached GPG signature (`.asc`) and is listed in
100
136
  a signed `SHA256SUMS` file; RPMs additionally carry embedded `rpmsign`
101
137
  signatures. The public key is committed at
@@ -104,7 +140,7 @@ signatures. The public key is committed at
104
140
  ## Command Line Usage
105
141
 
106
142
  <p align="center">
107
- <img src="https://raw.githubusercontent.com/allamiro/syslogcef/main/docs/demo.svg" alt="Animated demo of syslogcef converting different formats" width="820">
143
+ <img src="https://raw.githubusercontent.com/allamiro/syslog2cef/main/docs/demo.svg" alt="Animated demo of syslog2cef converting different formats" width="820">
108
144
  </p>
109
145
 
110
146
  ```bash
@@ -129,13 +165,21 @@ Options:
129
165
  | Option | Description |
130
166
  | ------ | ----------- |
131
167
  | `paths` | Input files; stdin is used when omitted. |
132
- | `-o, --output FILE` | Write CEF lines to a file instead of stdout. |
133
- | `--mode MODE` | Parser override: `rfc3164`, `rfc5424`, `rsyslog_json`, `rsyslog_file`, `journald_json`, `journald_short`, `journald_iso`. Auto-detected when omitted. |
168
+ | `-o, --output FILE` | Write CEF lines to a file instead of stdout. Accepts strftime codes for timed files (see "Timed output files"). |
169
+ | `-a, --append` | Append to `--output` instead of truncating it (implied for templated paths). |
170
+ | `--mode MODE` | Parser override: `rfc3164`, `rfc5424`, `rsyslog_json`, `rsyslog_file`, `journald_json`, `journald_short`, `journald_iso`, `cisco_seq`, `iso_syslog`, `kv`, or a name from `--patterns`. Auto-detected when omitted. |
134
171
  | `--mapping FILE` | Mapping JSON file. Auto-selected from message content when omitted. |
172
+ | `--patterns FILE` | Custom parser patterns (see "Custom Parsers"); may be repeated. |
135
173
  | `--tail` | Follow input files like `tail -f`. |
174
+ | `--listen PROTO:PORT` | Receive syslog over the network instead of files/stdin: `udp:514`, `tcp:5514`, or `udp:10.0.0.5:514`. |
175
+ | `--send URL` | Forward CEF to `udp://HOST:PORT`, `tcp://HOST:PORT`, or `kafka://BROKER:PORT/TOPIC` (needs the `kafka` extra). |
176
+ | `--eps N` | Rate-limit `--send` to at most N events per second. |
136
177
  | `--multiprocess` | Convert lines using a process pool. |
137
178
  | `--pool-size N` | Worker count for `--multiprocess` (default: CPU count minus one). |
179
+ | `--validate` | Check CEF extensions against the ArcSight dictionary; violations are logged as warnings. |
180
+ | `--strict` | Like `--validate`, but exit with an error on type or length violations. |
138
181
  | `--log-level LEVEL` | Python logging level (default `WARNING`). |
182
+ | `--version` | Print the version, copyright, license and author, then exit. |
139
183
 
140
184
  `python -m syslogcef` is equivalent to the `syslogcef` entry point.
141
185
 
@@ -161,7 +205,8 @@ cef = to_cef(normalized, mapping="my_mapping.json")
161
205
  ```
162
206
 
163
207
  Bundled mappings are importable from `syslogcef.mappings` (`CISCO_ASA`,
164
- `CISCO_IOS`, `F5`, `LINUX`, `VMWARE`, or `load_mapping(name)`).
208
+ `CISCO_IOS`, `F5`, `FORTINET`, `LINUX`, `SOPHOS`, `VMWARE`, or
209
+ `load_mapping(name)`).
165
210
 
166
211
  ## Mapping Files
167
212
 
@@ -181,7 +226,7 @@ normalized event's fields:
181
226
  "src": "%(src)s",
182
227
  "dst": "%(dst)s",
183
228
  "cs1Label": "rawEvent",
184
- "cs1": "%(raw_kv)s"
229
+ "cs1": "%(raw)s"
185
230
  }
186
231
  }
187
232
  ```
@@ -191,7 +236,8 @@ normalized event's fields:
191
236
  - `severity_map` translates syslog severity (0-7) to CEF severity (0-10);
192
237
  unmapped values pass through.
193
238
  - `extensions` maps CEF extension keys to templates. Extensions that
194
- resolve to an empty value are omitted.
239
+ resolve to an empty value are omitted, and so is a custom-field label
240
+ (`cs1Label`, `cn1Label`, ...) whose paired value is omitted.
195
241
  - Available template fields include `host`, `app`, `pid`, `msgid`, `msg`,
196
242
  `message_short` (first 120 characters), `raw`, `raw_kv`, `event_code`,
197
243
  `facility`, `severity`, `ts`, plus every key=value pair extracted from
@@ -204,6 +250,18 @@ extension keys fail with a configuration error instead of corrupting a record.
204
250
  See [docs/cef_fields.md](docs/cef_fields.md) for the full CEF extension
205
251
  dictionary.
206
252
 
253
+ ## Timestamps without a year
254
+
255
+ RFC3164, journald short, Cisco console lines and many device formats
256
+ stamp `Jan 1 12:34:56` with no year. syslogcef dates such a timestamp to
257
+ its most recent occurrence that is not more than one day ahead of the
258
+ current time: log lines describe events that already happened. A `Jan 1`
259
+ line converted in November is dated January of the current year, while a
260
+ line stamped just after midnight on New Year's Eve (a sender clock or
261
+ timezone slightly ahead) lands in the new year. Pass `now=` to
262
+ `parse_syslog`/`convert_line` to date archived files relative to when
263
+ they were written.
264
+
207
265
  ## Field Dictionary
208
266
 
209
267
  `syslogcef/dictionary.json` is the single source of truth for CEF field
@@ -255,9 +313,9 @@ syslogcef acme.log --patterns /etc/syslogcef/patterns.json
255
313
  - Named groups map to event fields: `pri`, `host`, `app`, `pid`,
256
314
  `msgid`, `msg`, and `ts`.
257
315
  - A `ts` group requires `timestamp_format`: a strptime format,
258
- `iso8601`, or `epoch`. Yearless formats get the same year-rollover
259
- inference as the built-in parsers; an unparseable timestamp never
260
- drops the event.
316
+ `iso8601`, or `epoch`. Yearless formats get the same year inference
317
+ as the built-in parsers (see "Timestamps without a year" below); an
318
+ unparseable timestamp never drops the event.
261
319
  - `priority` is `"after"` (default: tried after the built-ins, before
262
320
  the adaptive fallback) or `"before"` (tried first, overriding
263
321
  built-ins).
@@ -294,7 +352,7 @@ configuration in `/etc/conf.d/syslogcef`):
294
352
  - `/etc/logrotate.d/syslogcef` — daily rotation for flat `.cef` archives.
295
353
 
296
354
  ```bash
297
- sudo dnf install syslogcef-*.rpm
355
+ sudo dnf install syslog2cef-*.rpm
298
356
  sudo vi /etc/syslogcef/syslogcef.conf
299
357
  sudo systemctl enable --now syslogcef
300
358
  ```
@@ -377,8 +435,8 @@ issues for security reports.
377
435
  ## Development
378
436
 
379
437
  ```bash
380
- git clone https://github.com/allamiro/syslogcef.git
381
- cd syslogcef
438
+ git clone https://github.com/allamiro/syslog2cef.git
439
+ cd syslog2cef
382
440
  python -m venv .venv
383
441
  source .venv/bin/activate
384
442
  pip install -e .[test]
@@ -388,6 +446,23 @@ pytest
388
446
  Contributions are welcome — see [CONTRIBUTING.md](CONTRIBUTING.md). Notable
389
447
  changes are tracked in [CHANGELOG.md](CHANGELOG.md).
390
448
 
449
+ ## Citation
450
+
451
+ If you use syslog2cef in research or published work, please cite it. The
452
+ metadata is in [CITATION.cff](CITATION.cff), and GitHub's "Cite this
453
+ repository" button produces APA and BibTeX from it.
454
+
455
+ ```bibtex
456
+ @software{suliman_syslog2cef,
457
+ author = {Suliman, Tamir},
458
+ title = {syslog2cef: Convert syslog to ArcSight Common Event Format (CEF)},
459
+ version = {0.4.1},
460
+ year = {2026},
461
+ url = {https://github.com/allamiro/syslog2cef},
462
+ license = {MIT}
463
+ }
464
+ ```
465
+
391
466
  ## License
392
467
 
393
468
  MIT — see [LICENSE](LICENSE). Copyright (c) Tamir Suliman.
@@ -1,33 +1,23 @@
1
- Metadata-Version: 2.4
2
- Name: syslog2cef
3
- Version: 0.3.3
4
- Summary: Convert RFC3164/RFC5424 syslog lines into ArcSight CEF
5
- Author-email: Tamir Suliman <allamiro@gmail.com>
6
- Project-URL: Homepage, https://github.com/allamiro/syslogcef
7
- Project-URL: Issues, https://github.com/allamiro/syslogcef/issues
8
- Keywords: syslog,cef,logging,security
9
- Classifier: Programming Language :: Python :: 3
10
- Classifier: Programming Language :: Python :: 3 :: Only
11
- Classifier: License :: OSI Approved :: MIT License
12
- Classifier: Topic :: System :: Logging
13
- Requires-Python: >=3.9
14
- Description-Content-Type: text/markdown
15
- License-File: LICENSE
16
- Provides-Extra: test
17
- Requires-Dist: pytest>=7; extra == "test"
18
- Provides-Extra: kafka
19
- Requires-Dist: kafka-python>=2.0; extra == "kafka"
20
- Provides-Extra: fuzz
21
- Requires-Dist: hypothesis>=6; extra == "fuzz"
22
- Dynamic: license-file
1
+ <p align="center">
2
+ <img src="https://raw.githubusercontent.com/allamiro/syslog2cef/main/docs/logo.svg" alt="syslog2cef logo" width="540">
3
+ </p>
23
4
 
24
5
  <p align="center">
25
- <img src="https://raw.githubusercontent.com/allamiro/syslogcef/main/docs/logo.svg" alt="syslogcef logo" width="540">
6
+ <a href="https://github.com/allamiro/syslog2cef/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/allamiro/syslog2cef/ci.yml?branch=main&label=CI" alt="CI status"></a>
7
+ <a href="https://pypi.org/project/syslog2cef/"><img src="https://img.shields.io/pypi/v/syslog2cef" alt="PyPI version"></a>
8
+ <a href="https://pypi.org/project/syslog2cef/"><img src="https://img.shields.io/pypi/pyversions/syslog2cef" alt="Supported Python versions"></a>
9
+ <a href="https://pypistats.org/packages/syslog2cef"><img src="https://img.shields.io/pypi/dm/syslog2cef" alt="PyPI downloads per month"></a>
10
+ <a href="https://copr.fedorainfracloud.org/coprs/allamiro/syslogcef/"><img src="https://copr.fedorainfracloud.org/coprs/allamiro/syslogcef/package/syslogcef/status_image/last_build.png" alt="COPR build status"></a>
11
+ <a href="https://github.com/allamiro/syslog2cef/pkgs/container/syslog2cef"><img src="https://img.shields.io/badge/container-ghcr.io-blue?logo=docker" alt="Container image on ghcr.io"></a>
12
+ <a href="https://github.com/allamiro/syslog2cef/actions/workflows/fuzz.yml"><img src="https://img.shields.io/github/actions/workflow/status/allamiro/syslog2cef/fuzz.yml?branch=main&label=deep%20fuzz" alt="Deep fuzz status"></a>
13
+ <a href="https://github.com/astral-sh/ruff"><img src="https://img.shields.io/badge/lint-ruff-261230" alt="Linted with Ruff"></a>
14
+ <a href="LICENSE"><img src="https://img.shields.io/github/license/allamiro/syslog2cef" alt="MIT license"></a>
15
+ <a href="CITATION.cff"><img src="https://img.shields.io/badge/cite-CITATION.cff-informational" alt="Citation file"></a>
26
16
  </p>
27
17
 
28
- # syslogcef
18
+ # syslog2cef
29
19
 
30
- syslogcef converts syslog events into ArcSight Common Event Format (CEF). It
20
+ syslog2cef converts syslog events into ArcSight Common Event Format (CEF). It
31
21
  is a small, dependency-free Python package with a command line interface,
32
22
  built for feeding syslog data from network devices and Linux hosts into SIEM
33
23
  platforms that consume CEF.
@@ -36,11 +26,18 @@ platforms that consume CEF.
36
26
 
37
27
  - Automatic detection and parsing of multiple syslog dialects:
38
28
  RFC3164 (BSD), RFC5424 (including structured data), rsyslog JSON and
39
- file formats, and systemd journal exports (JSON, short, and ISO formats).
29
+ file formats, systemd journal exports (JSON, short, and ISO formats),
30
+ Cisco console/buffer lines, ISO-timestamp syslog, and key=value streams
31
+ (Fortinet, Sophos). Unknown layouts are learned adaptively.
40
32
  - Deterministic vendor/product mappings bundled for Cisco ASA, Cisco IOS,
41
- F5 BIG-IP, generic Linux, and VMware ESXi, with automatic mapping
42
- selection based on message content.
43
- - Custom mappings supplied as JSON files or Python dictionaries.
33
+ F5 BIG-IP, Fortinet FortiGate, Sophos XG Firewall, VMware ESXi, and
34
+ generic Linux, with automatic mapping selection based on message content.
35
+ - Custom mappings supplied as JSON files or Python dictionaries, and custom
36
+ parsers supplied as regex pattern files.
37
+ - Validation of CEF extension values against the ArcSight extension
38
+ dictionary (`--validate`, `--strict`).
39
+ - Network receiver (`--listen udp:514`) and forwarding to UDP, TCP, or
40
+ Kafka (`--send`), with optional rate limiting.
44
41
  - Escaping of untrusted log content in both CEF header and extension
45
42
  fields, so crafted messages cannot forge header fields or split records.
46
43
  - Streaming CLI with stdin/file input, tail (follow) mode across multiple
@@ -50,19 +47,25 @@ platforms that consume CEF.
50
47
 
51
48
  ## Installation
52
49
 
53
- From PyPI (the distribution is named `syslog2cef` because the `syslogcef`
54
- name on PyPI belongs to an unrelated project; the import package and CLI
55
- are still `syslogcef`):
50
+ From PyPI:
56
51
 
57
52
  ```bash
58
53
  pip install syslog2cef
59
54
  ```
60
55
 
56
+ > **Naming.** The project, this repository, the PyPI distribution and the
57
+ > RPM/DEB/APK packages are all `syslog2cef`. The command you run and the
58
+ > Python package you import are `syslogcef`, unchanged — as are the config
59
+ > paths (`/etc/syslogcef/`), the systemd units and the log directory, so
60
+ > upgrading from an earlier release needs no changes. The `syslogcef` name
61
+ > on PyPI belongs to an unrelated project, which is why the distribution
62
+ > has always been `syslog2cef`.
63
+
61
64
  From source:
62
65
 
63
66
  ```bash
64
- git clone https://github.com/allamiro/syslogcef.git
65
- cd syslogcef
67
+ git clone https://github.com/allamiro/syslog2cef.git
68
+ cd syslog2cef
66
69
  pip install .
67
70
  ```
68
71
 
@@ -70,21 +73,21 @@ The GitHub releases page also provides, for every version:
70
73
 
71
74
  - An RPM package (Fedora/RHEL) with a systemd service — see "Running as a
72
75
  Service" below.
73
- - A Debian package (`syslogcef_X.Y.Z-1_all.deb`) with the same systemd
74
- service: `sudo apt install ./syslogcef_X.Y.Z-1_all.deb`.
76
+ - A Debian package (`syslog2cef_X.Y.Z-1_all.deb`) with the same systemd
77
+ service: `sudo apt install ./syslog2cef_X.Y.Z-1_all.deb`.
75
78
  - An Alpine APK with an OpenRC service:
76
- `apk add --allow-untrusted syslogcef-X.Y.Z-r0.apk` (or install the
79
+ `apk add --allow-untrusted syslog2cef-X.Y.Z-r0.apk` (or install the
77
80
  signing key from [packaging/apk/syslogcef.rsa.pub](packaging/apk/syslogcef.rsa.pub)
78
81
  into `/etc/apk/keys/` first to verify).
79
- - A standalone executable (`syslogcef-X.Y.Z.pyz`) that runs on any system
80
- with Python 3.9+: `chmod +x syslogcef-X.Y.Z.pyz && ./syslogcef-X.Y.Z.pyz`.
82
+ - A standalone executable (`syslog2cef-X.Y.Z.pyz`) that runs on any system
83
+ with Python 3.9+: `chmod +x syslog2cef-X.Y.Z.pyz && ./syslog2cef-X.Y.Z.pyz`.
81
84
  - A source zip and sdist/wheel files.
82
85
 
83
86
  A multi-arch (amd64/arm64) container image is published to GitHub
84
87
  Container Registry on each release:
85
88
 
86
89
  ```bash
87
- docker run -i ghcr.io/allamiro/syslogcef < /var/log/syslog
90
+ docker run -i ghcr.io/allamiro/syslog2cef < /var/log/syslog
88
91
  ```
89
92
 
90
93
  Fedora, RHEL/Alma/Rocky 9 and 10, and CentOS Stream users can install
@@ -93,9 +96,13 @@ which rebuilds automatically from every commit:
93
96
 
94
97
  ```bash
95
98
  sudo dnf copr enable allamiro/syslogcef
96
- sudo dnf install syslogcef
99
+ sudo dnf install syslog2cef
97
100
  ```
98
101
 
102
+ The COPR project keeps its original name (`allamiro/syslogcef`) so that
103
+ already-enabled repositories keep working; the package it builds is
104
+ `syslog2cef`.
105
+
99
106
  Every asset ships with a detached GPG signature (`.asc`) and is listed in
100
107
  a signed `SHA256SUMS` file; RPMs additionally carry embedded `rpmsign`
101
108
  signatures. The public key is committed at
@@ -104,7 +111,7 @@ signatures. The public key is committed at
104
111
  ## Command Line Usage
105
112
 
106
113
  <p align="center">
107
- <img src="https://raw.githubusercontent.com/allamiro/syslogcef/main/docs/demo.svg" alt="Animated demo of syslogcef converting different formats" width="820">
114
+ <img src="https://raw.githubusercontent.com/allamiro/syslog2cef/main/docs/demo.svg" alt="Animated demo of syslog2cef converting different formats" width="820">
108
115
  </p>
109
116
 
110
117
  ```bash
@@ -129,13 +136,21 @@ Options:
129
136
  | Option | Description |
130
137
  | ------ | ----------- |
131
138
  | `paths` | Input files; stdin is used when omitted. |
132
- | `-o, --output FILE` | Write CEF lines to a file instead of stdout. |
133
- | `--mode MODE` | Parser override: `rfc3164`, `rfc5424`, `rsyslog_json`, `rsyslog_file`, `journald_json`, `journald_short`, `journald_iso`. Auto-detected when omitted. |
139
+ | `-o, --output FILE` | Write CEF lines to a file instead of stdout. Accepts strftime codes for timed files (see "Timed output files"). |
140
+ | `-a, --append` | Append to `--output` instead of truncating it (implied for templated paths). |
141
+ | `--mode MODE` | Parser override: `rfc3164`, `rfc5424`, `rsyslog_json`, `rsyslog_file`, `journald_json`, `journald_short`, `journald_iso`, `cisco_seq`, `iso_syslog`, `kv`, or a name from `--patterns`. Auto-detected when omitted. |
134
142
  | `--mapping FILE` | Mapping JSON file. Auto-selected from message content when omitted. |
143
+ | `--patterns FILE` | Custom parser patterns (see "Custom Parsers"); may be repeated. |
135
144
  | `--tail` | Follow input files like `tail -f`. |
145
+ | `--listen PROTO:PORT` | Receive syslog over the network instead of files/stdin: `udp:514`, `tcp:5514`, or `udp:10.0.0.5:514`. |
146
+ | `--send URL` | Forward CEF to `udp://HOST:PORT`, `tcp://HOST:PORT`, or `kafka://BROKER:PORT/TOPIC` (needs the `kafka` extra). |
147
+ | `--eps N` | Rate-limit `--send` to at most N events per second. |
136
148
  | `--multiprocess` | Convert lines using a process pool. |
137
149
  | `--pool-size N` | Worker count for `--multiprocess` (default: CPU count minus one). |
150
+ | `--validate` | Check CEF extensions against the ArcSight dictionary; violations are logged as warnings. |
151
+ | `--strict` | Like `--validate`, but exit with an error on type or length violations. |
138
152
  | `--log-level LEVEL` | Python logging level (default `WARNING`). |
153
+ | `--version` | Print the version, copyright, license and author, then exit. |
139
154
 
140
155
  `python -m syslogcef` is equivalent to the `syslogcef` entry point.
141
156
 
@@ -161,7 +176,8 @@ cef = to_cef(normalized, mapping="my_mapping.json")
161
176
  ```
162
177
 
163
178
  Bundled mappings are importable from `syslogcef.mappings` (`CISCO_ASA`,
164
- `CISCO_IOS`, `F5`, `LINUX`, `VMWARE`, or `load_mapping(name)`).
179
+ `CISCO_IOS`, `F5`, `FORTINET`, `LINUX`, `SOPHOS`, `VMWARE`, or
180
+ `load_mapping(name)`).
165
181
 
166
182
  ## Mapping Files
167
183
 
@@ -181,7 +197,7 @@ normalized event's fields:
181
197
  "src": "%(src)s",
182
198
  "dst": "%(dst)s",
183
199
  "cs1Label": "rawEvent",
184
- "cs1": "%(raw_kv)s"
200
+ "cs1": "%(raw)s"
185
201
  }
186
202
  }
187
203
  ```
@@ -191,7 +207,8 @@ normalized event's fields:
191
207
  - `severity_map` translates syslog severity (0-7) to CEF severity (0-10);
192
208
  unmapped values pass through.
193
209
  - `extensions` maps CEF extension keys to templates. Extensions that
194
- resolve to an empty value are omitted.
210
+ resolve to an empty value are omitted, and so is a custom-field label
211
+ (`cs1Label`, `cn1Label`, ...) whose paired value is omitted.
195
212
  - Available template fields include `host`, `app`, `pid`, `msgid`, `msg`,
196
213
  `message_short` (first 120 characters), `raw`, `raw_kv`, `event_code`,
197
214
  `facility`, `severity`, `ts`, plus every key=value pair extracted from
@@ -204,6 +221,18 @@ extension keys fail with a configuration error instead of corrupting a record.
204
221
  See [docs/cef_fields.md](docs/cef_fields.md) for the full CEF extension
205
222
  dictionary.
206
223
 
224
+ ## Timestamps without a year
225
+
226
+ RFC3164, journald short, Cisco console lines and many device formats
227
+ stamp `Jan 1 12:34:56` with no year. syslogcef dates such a timestamp to
228
+ its most recent occurrence that is not more than one day ahead of the
229
+ current time: log lines describe events that already happened. A `Jan 1`
230
+ line converted in November is dated January of the current year, while a
231
+ line stamped just after midnight on New Year's Eve (a sender clock or
232
+ timezone slightly ahead) lands in the new year. Pass `now=` to
233
+ `parse_syslog`/`convert_line` to date archived files relative to when
234
+ they were written.
235
+
207
236
  ## Field Dictionary
208
237
 
209
238
  `syslogcef/dictionary.json` is the single source of truth for CEF field
@@ -255,9 +284,9 @@ syslogcef acme.log --patterns /etc/syslogcef/patterns.json
255
284
  - Named groups map to event fields: `pri`, `host`, `app`, `pid`,
256
285
  `msgid`, `msg`, and `ts`.
257
286
  - A `ts` group requires `timestamp_format`: a strptime format,
258
- `iso8601`, or `epoch`. Yearless formats get the same year-rollover
259
- inference as the built-in parsers; an unparseable timestamp never
260
- drops the event.
287
+ `iso8601`, or `epoch`. Yearless formats get the same year inference
288
+ as the built-in parsers (see "Timestamps without a year" below); an
289
+ unparseable timestamp never drops the event.
261
290
  - `priority` is `"after"` (default: tried after the built-ins, before
262
291
  the adaptive fallback) or `"before"` (tried first, overriding
263
292
  built-ins).
@@ -294,7 +323,7 @@ configuration in `/etc/conf.d/syslogcef`):
294
323
  - `/etc/logrotate.d/syslogcef` — daily rotation for flat `.cef` archives.
295
324
 
296
325
  ```bash
297
- sudo dnf install syslogcef-*.rpm
326
+ sudo dnf install syslog2cef-*.rpm
298
327
  sudo vi /etc/syslogcef/syslogcef.conf
299
328
  sudo systemctl enable --now syslogcef
300
329
  ```
@@ -377,8 +406,8 @@ issues for security reports.
377
406
  ## Development
378
407
 
379
408
  ```bash
380
- git clone https://github.com/allamiro/syslogcef.git
381
- cd syslogcef
409
+ git clone https://github.com/allamiro/syslog2cef.git
410
+ cd syslog2cef
382
411
  python -m venv .venv
383
412
  source .venv/bin/activate
384
413
  pip install -e .[test]
@@ -388,6 +417,23 @@ pytest
388
417
  Contributions are welcome — see [CONTRIBUTING.md](CONTRIBUTING.md). Notable
389
418
  changes are tracked in [CHANGELOG.md](CHANGELOG.md).
390
419
 
420
+ ## Citation
421
+
422
+ If you use syslog2cef in research or published work, please cite it. The
423
+ metadata is in [CITATION.cff](CITATION.cff), and GitHub's "Cite this
424
+ repository" button produces APA and BibTeX from it.
425
+
426
+ ```bibtex
427
+ @software{suliman_syslog2cef,
428
+ author = {Suliman, Tamir},
429
+ title = {syslog2cef: Convert syslog to ArcSight Common Event Format (CEF)},
430
+ version = {0.4.1},
431
+ year = {2026},
432
+ url = {https://github.com/allamiro/syslog2cef},
433
+ license = {MIT}
434
+ }
435
+ ```
436
+
391
437
  ## License
392
438
 
393
439
  MIT — see [LICENSE](LICENSE). Copyright (c) Tamir Suliman.
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "syslog2cef"
7
- version = "0.3.3"
7
+ version = "0.4.1"
8
8
  description = "Convert RFC3164/RFC5424 syslog lines into ArcSight CEF"
9
9
  authors = [{name = "Tamir Suliman", email = "allamiro@gmail.com"}]
10
10
  readme = "README.md"
@@ -12,6 +12,12 @@ requires-python = ">=3.9"
12
12
  classifiers = [
13
13
  "Programming Language :: Python :: 3",
14
14
  "Programming Language :: Python :: 3 :: Only",
15
+ "Programming Language :: Python :: 3.9",
16
+ "Programming Language :: Python :: 3.10",
17
+ "Programming Language :: Python :: 3.11",
18
+ "Programming Language :: Python :: 3.12",
19
+ "Programming Language :: Python :: 3.13",
20
+ "Programming Language :: Python :: 3.14",
15
21
  "License :: OSI Approved :: MIT License",
16
22
  "Topic :: System :: Logging",
17
23
  ]
@@ -19,8 +25,8 @@ keywords = ["syslog", "cef", "logging", "security"]
19
25
  dependencies = []
20
26
 
21
27
  [project.urls]
22
- Homepage = "https://github.com/allamiro/syslogcef"
23
- Issues = "https://github.com/allamiro/syslogcef/issues"
28
+ Homepage = "https://github.com/allamiro/syslog2cef"
29
+ Issues = "https://github.com/allamiro/syslog2cef/issues"
24
30
 
25
31
  [project.optional-dependencies]
26
32
  test = [