diff --git a/doc/devguide/Makefile.am b/doc/devguide/Makefile.am index 3f8ac6d1c7..44317c606d 100644 --- a/doc/devguide/Makefile.am +++ b/doc/devguide/Makefile.am @@ -2,9 +2,24 @@ EXTRA_DIST = \ conf.py \ _static \ index.rst \ - code-submission-process.rst \ - code-style.rst \ - app-layer + extending/detect/index.rst \ + extending/decoder/index.rst \ + extending/index.rst \ + extending/app-layer/index.rst \ + extending/app-layer/parser.rst \ + extending/capture/index.rst \ + extending/output/index.rst \ + internals/engines/index.rst \ + internals/threading/index.rst \ + internals/index.rst \ + internals/pipeline/index.rst \ + internals/datastructs/index.rst \ + codebase/unittests.rst \ + codebase/index.rst \ + codebase/code-style.rst \ + codebase/contributing/code-submission-process.rst \ + codebase/contributing/index.rst \ + codebase/fuzz-testing.rst if HAVE_SPHINXBUILD diff --git a/doc/devguide/code-style.rst b/doc/devguide/codebase/code-style.rst similarity index 100% rename from doc/devguide/code-style.rst rename to doc/devguide/codebase/code-style.rst diff --git a/doc/devguide/code-submission-process.rst b/doc/devguide/codebase/contributing/code-submission-process.rst similarity index 100% rename from doc/devguide/code-submission-process.rst rename to doc/devguide/codebase/contributing/code-submission-process.rst diff --git a/doc/devguide/codebase/contributing/index.rst b/doc/devguide/codebase/contributing/index.rst new file mode 100644 index 0000000000..1338054eab --- /dev/null +++ b/doc/devguide/codebase/contributing/index.rst @@ -0,0 +1,7 @@ +Contributing +============ + +.. toctree:: + :maxdepth: 2 + + code-submission-process diff --git a/doc/devguide/codebase/fuzz-testing.rst b/doc/devguide/codebase/fuzz-testing.rst new file mode 100644 index 0000000000..84e678cd62 --- /dev/null +++ b/doc/devguide/codebase/fuzz-testing.rst @@ -0,0 +1,31 @@ +Fuzz Testing +============ + +To enable fuzz targets compilation, add `--enable-fuzztargets` to configure. + +.. note:: This changes various parts of Suricata making the `suricata` binary + unsafe for production use. + +The targets can be used with libFuzzer, AFL and other fuzz platforms. + + +Running the Fuzzers +------------------- + +TODO. For now see src/tests/fuzz/README + +Reproducing issues +^^^^^^^^^^^^^^^^^^ + + +Extending Coverage +------------------ + +Adding Fuzz Targets +------------------- + + +Oss-Fuzz +-------- + +Suricata is continuesly fuzz tested in Oss-Fuzz. See https://github.com/google/oss-fuzz/tree/master/projects/suricata diff --git a/doc/devguide/codebase/index.rst b/doc/devguide/codebase/index.rst new file mode 100644 index 0000000000..e5c4ba058a --- /dev/null +++ b/doc/devguide/codebase/index.rst @@ -0,0 +1,10 @@ +Working with the Codebase +========================= + +.. toctree:: + :maxdepth: 2 + + contributing/index.rst + code-style + unittests + fuzz-testing diff --git a/doc/devguide/codebase/unittests.rst b/doc/devguide/codebase/unittests.rst new file mode 100644 index 0000000000..a8be84a372 --- /dev/null +++ b/doc/devguide/codebase/unittests.rst @@ -0,0 +1,12 @@ +Unittests +========= + +Unittests are a great way to create tests that can check the internal state +of parsers, structures and other objects. + +Tests should: + +- use FAIL/PASS macros +- be deterministic +- not leak memory on PASS +- not use conditions diff --git a/doc/devguide/app-layer/index.rst b/doc/devguide/extending/app-layer/index.rst similarity index 100% rename from doc/devguide/app-layer/index.rst rename to doc/devguide/extending/app-layer/index.rst diff --git a/doc/devguide/app-layer/parser.rst b/doc/devguide/extending/app-layer/parser.rst similarity index 100% rename from doc/devguide/app-layer/parser.rst rename to doc/devguide/extending/app-layer/parser.rst diff --git a/doc/devguide/extending/capture/index.rst b/doc/devguide/extending/capture/index.rst new file mode 100644 index 0000000000..2b84ae6762 --- /dev/null +++ b/doc/devguide/extending/capture/index.rst @@ -0,0 +1,2 @@ +Packet Capture +============== diff --git a/doc/devguide/extending/decoder/index.rst b/doc/devguide/extending/decoder/index.rst new file mode 100644 index 0000000000..9c26117533 --- /dev/null +++ b/doc/devguide/extending/decoder/index.rst @@ -0,0 +1,2 @@ +Packet Decoder +============== diff --git a/doc/devguide/extending/detect/index.rst b/doc/devguide/extending/detect/index.rst new file mode 100644 index 0000000000..1dde177d88 --- /dev/null +++ b/doc/devguide/extending/detect/index.rst @@ -0,0 +1,2 @@ +Detection +========= diff --git a/doc/devguide/extending/index.rst b/doc/devguide/extending/index.rst new file mode 100644 index 0000000000..bcdabeffd7 --- /dev/null +++ b/doc/devguide/extending/index.rst @@ -0,0 +1,11 @@ +Extending Suricata +================== + +.. toctree:: + :maxdepth: 2 + + capture/index.rst + decoder/index.rst + app-layer/index.rst + detect/index.rst + output/index.rst diff --git a/doc/devguide/extending/output/index.rst b/doc/devguide/extending/output/index.rst new file mode 100644 index 0000000000..559723ee0a --- /dev/null +++ b/doc/devguide/extending/output/index.rst @@ -0,0 +1,7 @@ +Output +====== + +Introduction +------------ + +Extending Suricata's alert and event output. diff --git a/doc/devguide/index.rst b/doc/devguide/index.rst index 85d6eab217..48007de2c3 100644 --- a/doc/devguide/index.rst +++ b/doc/devguide/index.rst @@ -5,6 +5,6 @@ Suricata Developer Guide :numbered: :maxdepth: 2 - code-submission-process - code-style - app-layer/index.rst + codebase/index.rst + internals/index.rst + extending/index.rst diff --git a/doc/devguide/internals/datastructs/index.rst b/doc/devguide/internals/datastructs/index.rst new file mode 100644 index 0000000000..cb67988b70 --- /dev/null +++ b/doc/devguide/internals/datastructs/index.rst @@ -0,0 +1,9 @@ +Important Data Structures +========================= + +Introduction +------------ + +This section explains the most important Suricata Data structures. + +For a complete overview, see the doxygen: https://doxygen.openinfosecfoundation.org diff --git a/doc/devguide/internals/engines/index.rst b/doc/devguide/internals/engines/index.rst new file mode 100644 index 0000000000..6944a69761 --- /dev/null +++ b/doc/devguide/internals/engines/index.rst @@ -0,0 +1,11 @@ +Engines +======= + +Flow +---- + +Stream +------ + +Defrag +------ diff --git a/doc/devguide/internals/index.rst b/doc/devguide/internals/index.rst new file mode 100644 index 0000000000..29a8e59520 --- /dev/null +++ b/doc/devguide/internals/index.rst @@ -0,0 +1,10 @@ +Suricata Internals +================== + +.. toctree:: + :maxdepth: 2 + + pipeline/index.rst + threading/index.rst + datastructs/index.rst + engines/index.rst diff --git a/doc/devguide/internals/pipeline/index.rst b/doc/devguide/internals/pipeline/index.rst new file mode 100644 index 0000000000..8acd52396f --- /dev/null +++ b/doc/devguide/internals/pipeline/index.rst @@ -0,0 +1,2 @@ +Packet Pipeline +=============== diff --git a/doc/devguide/internals/threading/index.rst b/doc/devguide/internals/threading/index.rst new file mode 100644 index 0000000000..b89b6d0eb3 --- /dev/null +++ b/doc/devguide/internals/threading/index.rst @@ -0,0 +1,2 @@ +Threading +=========