Skip to content

Commit f21b5d6

Browse files
atomicturtleatomicturtle
committed
Reorganize and update OSSEC docs for v4.1.0
Restructure the Sphinx site for discoverability and align documentation with ossec-hids v4.1.0. Phase 1 improves navigation and build plumbing; Phase 2 closes content gaps against the current codebase. Layout and organization: - Restructure index.rst with Getting Started, Reference, Release Notes, and About sections; demote OSSEC+ promo to a note - Wire orphaned content into the toctree (manual notes, log samples, changelog, about) - Split internal_options.conf reference into per-daemon pages - Remove stale docs/index.rst alternate master and unused globaltoc template - Add ossec_config quick-reference table and cross-links between manual, program, and syntax pages Build and CI: - Bump release to 4.1.0; enable xml_domain extension for .trst object directives - Trim requirements.txt to sphinx, furo, and myst-parser - Add GitHub Actions workflow to build HTML documentation - Fix Makefile OSPatrol branding leftovers New and updated content (v4.1.0 alignment): - Add upgrade/migration guide (AES, SHA-256 FIM, crypto matrix) - Add journald monitoring, remoted architecture/tuning, and systemd deployment - Document journald log_format, allow_list alias, and missing internal_options keys (remoted syslog TCP pool, authd worker pool, analysisd.geoip_jsonout) - Rewrite JSON alert format docs; update syscheck narrative and changelog - Add ossec-regex-convert program page and doc maintenance checklist - Fix ossec-analysisd -f option description Signed-off-by: Scott R. Shinn <scott@atomicorp.com>
1 parent 136e726 commit f21b5d6

48 files changed

Lines changed: 993 additions & 258 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/docs.yml‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
name: Build documentation
2+
3+
on:
4+
push:
5+
branches: [master, docs/refresh-v4.1]
6+
pull_request:
7+
branches: [master]
8+
9+
jobs:
10+
build:
11+
runs-on: ubuntu-latest
12+
steps:
13+
- uses: actions/checkout@v4
14+
15+
- name: Set up Python
16+
uses: actions/setup-python@v5
17+
with:
18+
python-version: '3.12'
19+
20+
- name: Install dependencies
21+
run: pip install -r requirements.txt
22+
23+
- name: Build HTML
24+
run: make html
25+
26+
- name: Upload build artifact
27+
uses: actions/upload-artifact@v4
28+
with:
29+
name: html-docs
30+
path: _build/html

‎Makefile‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -86,17 +86,17 @@ qthelp:
8686
@echo
8787
@echo "Build finished; now you can run "qcollectiongenerator" with the" \
8888
".qhcp project file in $(BUILDDIR)/qthelp, like this:"
89-
@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/OSPatrol.qhcp"
89+
@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/OSSEC.qhcp"
9090
@echo "To view the help file:"
91-
@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/OSPatrol.qhc"
91+
@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/OSSEC.qhc"
9292

9393
devhelp:
9494
$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
9595
@echo
9696
@echo "Build finished."
9797
@echo "To view the help file:"
98-
@echo "# mkdir -p $$HOME/.local/share/devhelp/OSPatrol"
99-
@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/OSPatrol"
98+
@echo "# mkdir -p $$HOME/.local/share/devhelp/OSSEC"
99+
@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/OSSEC"
100100
@echo "# devhelp"
101101

102102
epub:

‎_ext/xml_domain.py‎

Lines changed: 1 addition & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,4 @@
22

33

44
def setup(app):
5-
app.add_object_type('element', 'xml', '%s')
6-
app.add_object_type('attribute', 'xml', 'pair: %s; Attribute')
7-
app.add_object_type('intopt', 'OS','%s')
8-
5+
app.add_object_type('object', 'obj', '%s')

‎_templates/globaltoc.html‎

Lines changed: 0 additions & 9 deletions
This file was deleted.

‎about/index.rst‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
.. _about-index:
2+
3+
About & Contributing
4+
====================
5+
6+
.. toctree::
7+
:maxdepth: 2
8+
9+
ossec_logic
10+
active_response_logic
11+
how_to_help
12+
translators

‎changelog.rst‎

Lines changed: 7 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
.. _changelog:
2+
13
Change Log
24
----------
35

@@ -22,29 +24,12 @@ Change Log
2224
- Added support for OpenSUSE Leap 15/16 and Debian 13 (Trixie).
2325
- Updated CI/CD pipeline for more robust packaging.
2426

25-
upcoming (2015/02/21 20:11 +00:00)
26-
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
27+
Older releases
28+
~~~~~~~~~~~~~~
2729

28-
- `#553 <https://github.com/ossec/ossec-hids/pull/553>`__ Use the
29-
MAKEBIN variable instead of hardcoded make (@ddpbsd)
30-
- `#551 <https://github.com/ossec/ossec-hids/pull/551>`__ Output
31-
alerts.json, newline delimited json, beside the alerts.log file.
32-
(@jondb)
33-
- `#547 <https://github.com/ossec/ossec-hids/pull/547>`__ Feature/nfs
34-
exclusion v2 (@reyjrar)
35-
- `#549 <https://github.com/ossec/ossec-hids/pull/549>`__ Fixed typo
36-
(@gustavo-gomez)
37-
- `#548 <https://github.com/ossec/ossec-hids/pull/548>`__ Fix
38-
misspelling of 'source' (@DazWorrall)
39-
- `#546 <https://github.com/ossec/ossec-hids/pull/546>`__ several
40-
Coverity fixes (@cgzones)
41-
- `#545 <https://github.com/ossec/ossec-hids/pull/545>`__ remove
42-
coverity plugin from travis, because it does not work properly
43-
(@cgzones)
44-
- `#537 <https://github.com/ossec/ossec-hids/pull/537>`__ fix most gcc
45-
-Wall -Wextra warnings in windows build (@cgzones)
46-
- `#544 <https://github.com/ossec/ossec-hids/pull/544>`__ Correct some
47-
spelling, and update based on ossec-docs (@ddpbsd)
30+
Release notes for OSSEC 3.x and earlier are preserved below. For the latest
31+
source-of-truth changelog, see the `ossec-hids CHANGELOG.md
32+
<https://github.com/ossec/ossec-hids/blob/main/CHANGELOG.md>`_ on GitHub.
4833

4934
2.9.0-beta03 (2015/02/09 14:01 +00:00)
5035
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

‎conf.py‎

Lines changed: 20 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,11 @@
33
# For the full list of built-in configuration values, see the documentation:
44
# https://www.sphinx-doc.org/en/master/usage/configuration.html
55

6+
import os
7+
import sys
8+
9+
sys.path.insert(0, os.path.abspath('_ext'))
10+
611
# -- Project information -----------------------------------------------------
712
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
813

@@ -16,35 +21,40 @@
1621

1722
extensions = [
1823
'myst_parser',
24+
'xml_domain',
1925
]
2026

2127
source_suffix = {
2228
'.rst': 'restructuredtext',
2329
'.md': 'markdown',
2430
}
2531

32+
exclude_patterns = [
33+
'_build',
34+
'Thumbs.db',
35+
'.DS_Store',
36+
'conf.py.bak',
37+
'_templates/*.bak',
38+
]
39+
2640
# Optional: Enable MyST extensions
2741
myst_enable_extensions = [
28-
"amsmath", # Math support
29-
"colon_fence", # ::: fenced blocks
30-
"deflist", # Definition lists
31-
"fieldlist", # Field lists for directives
32-
"html_admonition", # Admonitions
33-
"html_image", # Render Markdown images
42+
"amsmath",
43+
"colon_fence",
44+
"deflist",
45+
"fieldlist",
46+
"html_admonition",
47+
"html_image",
3448
]
3549

3650
# Paths for custom templates and static files
3751
templates_path = ['_templates']
3852
html_static_path = ['_static']
3953

40-
# Not bad
4154
html_theme = "furo"
4255

43-
html_static_path = ['_static']
44-
4556
html_css_files = [
4657
'custom.css',
4758
]
4859

4960
html_logo = "ossec_logo_bare_small.png"
50-

‎docs/development/doc-maintenance.rst‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
.. _doc-maintenance:
2+
3+
Documentation maintenance
4+
=========================
5+
6+
When changing ``ossec-hids``, update ``ossec-docs`` in the same release cycle when:
7+
8+
* **Config parsers** (``src/config/*.c``) gain or change XML elements → update the
9+
matching ``docs/syntax/ossec_config.*.trst`` file.
10+
* **``internal_options.conf``** keys change → update ``docs/syntax/internal_options.*.trst``.
11+
* **Breaking changes** → update :ref:`upgrade-migration` and ``changelog.rst``.
12+
* **New CLI tools** in ``src/util/`` → add a page under ``docs/programs/``.
13+
14+
Build locally:
15+
16+
.. code-block:: console
17+
18+
pip install -r requirements.txt
19+
make html
20+
21+
HTML output is written to ``_build/html/``.
22+
23+
Config audit checklist
24+
----------------------
25+
26+
Compare parser XML tag names in ``src/config/`` against ``docs/syntax/*.trst``:
27+
28+
+----------------------+--------------------------------+
29+
| Parser | Documentation |
30+
+======================+================================+
31+
| ``global-config.c`` | ``ossec_config.global.trst`` |
32+
| ``localfile-config.c`` | ``ossec_config.localfile.trst`` |
33+
| ``remote-config.c`` | ``ossec_config.remote.trst`` |
34+
| ``client-config.c`` | ``ossec_config.client.trst`` |
35+
| ``syscheck-config.c`` | ``ossec_config.syscheck.trst`` |
36+
+----------------------+--------------------------------+
37+
38+
Compare ``etc/internal_options.conf`` keys against ``docs/syntax/internal_options.*.trst``.

‎docs/formats/json.rst‎

Lines changed: 60 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -2,39 +2,68 @@
22
JSON Format
33
###########
44

5-
At this time we have one alert JSON formatted messages.
5+
OSSEC can write alerts in JSON format to ``/var/ossec/logs/alerts/alerts.json`` when
6+
``jsonout_output`` is enabled in ``<global>``. Each line is one JSON object.
67

7-
Also see manual/output/json-alert-log-output.
8+
Enable JSON output
9+
------------------
10+
11+
.. code-block:: xml
12+
13+
<global>
14+
<jsonout_output>yes</jsonout_output>
15+
</global>
16+
17+
Example alert
18+
-------------
819

920
.. code-block:: json
1021
11-
{
12-
"rule":1000,
13-
"level":1,
14-
"comment":"This is a comment",
15-
"sidid":1111,
16-
"cve":"cve-1001-1000",
17-
"action":"drop",
18-
"srcip":"10.1.1.1",
19-
"srcport":"1000",
20-
"srcuser":"root",
21-
"dstip":"10.2.2.2",
22-
"dstport":"2000",
23-
"dstuser":"root",
24-
"location":"/var/log/auth.log",
25-
"full_log":"This is the full log message",
26-
"file":{
27-
"path":"/etc/",
28-
"md5_before":"XXXXXXXXXXXXXXXXXXXX",
29-
"md5_after":"YYYYYYYYYYYYYYYYYYYY",
30-
"sha1_before":"XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
31-
"sha1_after":"YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY",
32-
"owner_before":"root",
33-
"owner_after":"nobody",
34-
"gowner_before":"root",
35-
"gowner_after":"nodody",
36-
"perm_before":660,
37-
"perm_after":777,
38-
}
39-
}
22+
{
23+
"timestamp": "2026-06-28T12:00:00.000+0000",
24+
"rule": {
25+
"level": 5,
26+
"description": "SSHD authentication success.",
27+
"id": "5715",
28+
"groups": ["syslog", "sshd", "authentication_success"]
29+
},
30+
"agent": {
31+
"id": "001",
32+
"name": "agent01"
33+
},
34+
"manager": {
35+
"name": "ossec-manager"
36+
},
37+
"id": "1234567890.12345",
38+
"full_log": "Jun 28 12:00:00 agent01 sshd[1234]: Accepted publickey for user",
39+
"decoder": {
40+
"name": "sshd"
41+
},
42+
"location": "/var/log/auth.log"
43+
}
44+
45+
Common fields
46+
-------------
47+
48+
+------------------+----------------------------------------------------------+
49+
| Field | Description |
50+
+==================+==========================================================+
51+
| ``timestamp`` | When OSSEC processed the event |
52+
| ``rule.level`` | Alert severity (0–16) |
53+
| ``rule.id`` | Rule ID that matched |
54+
| ``rule.description`` | Rule text |
55+
| ``rule.groups`` | Rule groups (also exposed as ``rule.group`` in some builds) |
56+
| ``agent.id`` | Agent ID (manager/local if absent) |
57+
| ``agent.name`` | Agent hostname |
58+
| ``full_log`` | Original log line or message |
59+
| ``srcip`` | Source IP when extracted by decoder |
60+
| ``dstuser`` | Destination user when extracted |
61+
| ``location`` | Log source path or label |
62+
| ``syscheck`` | FIM details when present (hashes, paths, ownership) |
63+
| ``GeoLocation`` | Present when GeoIP is enabled and ``analysisd.geoip_jsonout=1`` |
64+
+------------------+----------------------------------------------------------+
65+
66+
File integrity (syscheck) alerts may include ``md5``, ``sha1``, and ``sha256`` before/after
67+
fields inside the ``syscheck`` object.
4068

69+
Also see :ref:`manual-out-json` and :doc:`alerts </docs/formats/alerts>`.

‎docs/index.rst‎

Lines changed: 0 additions & 63 deletions
This file was deleted.

0 commit comments

Comments
 (0)