zlib1g-dev
# Checking out the branch is not as simple as "checking out".
#
- # In case master has any new commits since we branched off, github will
- # automatically add a "merge commit" from our branch to master and check
+ # In case main has any new commits since we branched off, github will
+ # automatically add a "merge commit" from our branch to main and check
# this out instead of the original last commit on the branch.
#
# This screws up git clang-format as it'll also format the "merge commit"
# and essentially report any formatting issues in the "merge commit".
- # However, we really don't care about any of the new commits on master.
+ # However, we really don't care about any of the new commits on main.
#
# There are supposed to be ways to use with/ref to fix that and while
# they work perfectly well for pull requests within the forked repo, none
second_last_commit_sha=$(git log --pretty=%H -2 |tail -1)
echo "$last_commit_subject" | grep -e "^Merge $second_last_commit_sha into [0-9a-fA-F]*$" > /dev/null 2>&1
if [ $? -eq 0 ]; then
- # Last commit was a merge to master - ignore
+ # Last commit was a merge to main - ignore
echo "Found github merge commit - checking out real last commit instead..."
git checkout $second_last_commit_sha
else
# Suricata
[](https://bugs.chromium.org/p/oss-fuzz/issues/list?sort=-opened&can=1&q=proj:suricata)
-[](https://codecov.io/gh/OISF/suricata)
+[](https://codecov.io/gh/OISF/suricata)
## Introduction
3.
- Create a branch for your work. This will make a copy of the current branch (master) and name it "new_feature". Now you can work in this new branch without breaking the main one.
+ Create a branch for your work. This will make a copy of the current branch (main) and name it "new_feature". Now you can work in this new branch without breaking the main one.
git checkout -b new_feature
5.
- When you are ready to send your local changes back to the Rubinius repository, you first need to ensure that your local copy is up-to-date. First, ensure you have committed your local changes. Then switch from your topic branch to the master branch.
+ When you are ready to send your local changes back to the Rubinius repository, you first need to ensure that your local copy is up-to-date. First, ensure you have committed your local changes. Then switch from your topic branch to the main branch.
- git checkout master
+ git checkout main
6.
Switch back to your topic branch and integrate any new changes. The git rebase command will save your changes away, update the topic branch, and then reapply them.
git checkout new_feature
- git rebase master
+ git rebase main
Warning! If you are sharing a branch, you must use:
- git merge master
+ git merge main
Rebase causes the commit layout to change and will confuse anyone you've shared this branch with.
9.
- Now, switch back to the master branch and merge your changes from the topic branch
+ Now, switch back to the main branch and merge your changes from the topic branch
- git checkout master
+ git checkout main
git merge new_feature
10.
git branch -d new_feature
-When you're familiar with the workflow, you can use the rake tasks to help you out. For example, rake git will fetch the latest code from remote repo, rebase the current branch to master, fast-forward the changes to master and push the commits to the remote. This saves a lot of typing. Check rake -T git for all the git related tasks.
+When you're familiar with the workflow, you can use the rake tasks to help you out. For example, rake git will fetch the latest code from remote repo, rebase the current branch to main, fast-forward the changes to main and push the commits to the remote. This saves a lot of typing. Check rake -T git for all the git related tasks.
Taken from: http://rubinius.lighthouseapp.com/projects/5089/using-git
<https://json-schema.org/>`_ specification and can be found in
``etc/schema.json``. If your distribution does not contain this file,
it can be viewed online at
-https://github.com/OISF/suricata/blob/master/etc/schema.json, but note
+https://github.com/OISF/suricata/blob/main/etc/schema.json, but note
that it is version-specific and may change between major versions of
Suricata.
In case you have multiple commits on your branch already and forgot to
format them you can fix that up as well.
-The following command will format every commit in your branch off master and
+The following command will format every commit in your branch off main and
rewrite history using the existing commit metadata.
Tip: Create a new version of your branch first and run this off the new version.
# Or with script:
$ scripts/clang-format.sh branch
-Note the usage of ``first_commit_on_your_branch^``, not ``master``, to avoid picking up
-new commits on ``master`` in case you've updated master since you've branched.
+Note the usage of ``first_commit_on_your_branch^``, not ``main``, to avoid picking up
+new commits on ``main`` in case you've updated main since you've branched.
Check formatting
~~~~~~~~~~~~~~~~
+------------+---------------+-----------+
Also, check the existing code. If yours is wildly different, it's wrong.
-Example: https://github.com/oisf/suricata/blob/master/src/decode-ethernet.c
+Example: https://github.com/oisf/suricata/blob/main/src/decode-ethernet.c
Rust
****
- **Static and dynamic analysis tools**: to help in finding bugs, memory leaks and other issues (like `scan-build <https://clang-analyzer.llvm.org/scan-build.html#scanbuild_basicusage>`_, from `clang`, which is also used for our C formatting checks; or ASAN, which checks for memory issues);
- **Fuzz testing**: especially good for uncovering existing, often non-trivial bugs. For more on how to fuzz test Suricata, check :doc:`fuzz-testing`;
- **CI checks**: each PR submitted to the project's public repositories will be run against a suit of Continuous Integration
- workflows, as part of our QA process. Those cover: formatting and commit checks; fuzz tests (CI Fuzz), and several builds. See our `github workflows <https://github.com/OISF/suricata/tree/master/.github/workflows>`_ for details and those in
+ workflows, as part of our QA process. Those cover: formatting and commit checks; fuzz tests (CI Fuzz), and several builds. See our `github workflows <https://github.com/OISF/suricata/tree/main/.github/workflows>`_ for details and those in
action at `<https://github.com/OISF/suricata/actions>`_.
.. note:: If you can run unit tests or other checks and report failures in our `issue tracker <https://redmine.openinfosecfoundation.org/projects/suricata/issues>`_, that is rather useful and appreciated!
Code Examples
^^^^^^^^^^^^^
-An example from the `DNS parser <https://github.com/OISF/suricata/blob/master/rust/src/dns/parser.rs#L417>`_. This
+An example from the `DNS parser <https://github.com/OISF/suricata/blob/main/rust/src/dns/parser.rs#L417>`_. This
checks that the given raw input (note the comments indicating what it means), once processed by ``dns_parse_name`` yields
the expected result, including the unparsed portion.
* Old stable release
For example, at the moment, there are 3 releases based on these Suricata branches:
- * master: 8.0.0-dev, current development branch
+ * main: 8.0.0-dev, current development branch
* main-7.0.x: major stable release (note we're changing our naming conventions)
* master-6.0.x: old stable release
sometimes we'll miss those.
The general principle used to determine what will be backported is:
- * security fixes (please see our `Security Policy <https://github.com/OISF/suricata/blob/master/SECURITY.md>`_)
+ * security fixes (please see our `Security Policy <https://github.com/OISF/suricata/blob/main/SECURITY.md>`_)
* bug fixes
* in some cases, new features are backported if there are sufficient reasons to
backport a new feature.
Then, also periodically, we will create backport issues from those items
identified in the previous steps. When doing so, we will evaluate what are the
-relevant target backport releases. Some issues reported against master or the
+relevant target backport releases. Some issues reported against main or the
current Suricata release may not apply to older releases.
Git Backport Workflow
---------------------
If you are working on a task that needs to be backported, only start the
-backporting process once the PR for master has been merged. Then:
+backporting process once the PR for main has been merged. Then:
* *Identify the commit(s) needed* for the backport. Start with the PR that merged
- the commits into master and select only the commits from the issue being
+ the commits into main and select only the commits from the issue being
backported.
* *Bring each commit into the new branch,* one at a time -- starting with the
oldest commit. Use ``git cherry-pick -x commit-hash``, where ``commit-hash``
- is the hash to the commit already in master or main-7.0x that is being
+ is the hash to the commit already in main or main-7.0x that is being
backported, as it maintains the linkage with said cherry-picked commit.
* *Resolve conflicts:* Some of the cherry-picked commits may contain merge
conflicts. If the conflicts are small, include the corrections in the
.. Note:: Exceptions
- Sometimes, the fix for master will not work for the stable or old releases.
+ Sometimes, the fix for main will not work for the stable or old releases.
In such cases, the backporting process won't be through cherry-picking, but
through actually implementing a fix for the specific version.
#. Incremental pull requests need to describe changes since the last PR
#. Link to the ticket(s) that are addressed to it.
#. When fixing an issue, update the issue status to ``In Review`` after submitting the PR.
-#. Pull requests are automatically tested using github actions (https://github.com/OISF/suricata/blob/master/.github/workflows/builds.yml).
+#. Pull requests are automatically tested using github actions (https://github.com/OISF/suricata/blob/main/.github/workflows/builds.yml).
Failing builds won't be considered and should be closed immediately.
#. Pull requests that change, or add a feature should include a documentation update commit
#. Agree to and sign our :ref:`Contribution Agreement<contribution-agreement>`
#. Communicate early, and use the :ref:`preferred channels <communication-channels>`
#. :ref:`claim-ticket`
-#. :ref:`Fork from master <what-branch-to-work-on>`
+#. :ref:`Fork from main <what-branch-to-work-on>`
#. Follow our :ref:`Coding Style`
#. Use our :ref:`documentation-style`
#. Stick to our :ref:`commit guidelines<commits>`
* master-x.x.x (e.g. master-6.0.x)
* main-x.x.x (e.g. main-7.0.x)
- * master
+ * main
-The ones with version numbers are stable branches. **master** is the development branch.
+The ones with version numbers are stable branches. **main** is the development branch.
The stable branch should only be worked on for important bug fixes or other
needed :doc:`backports<backports-guide>`. Those are mainly expected from more
experienced contributors.
Development of new features or large scale redesign is done in the development
-branch. New development and new contributors should work with *master* except
+branch. New development and new contributors should work with *main* except
in very special cases - which should and would be discussed with us first.
If in doubt, please reach out to us via :ref:`Redmine, Discord or
It is only necessary to invoke the role once per document. One can see these
being invoked in our introduction to the rule language (see `Rules intro
-<https://raw.githubusercontent.com/OISF/suricata/master/doc/userguide/rules/intro.rst>`_).
+<https://raw.githubusercontent.com/OISF/suricata/main/doc/userguide/rules/intro.rst>`_).
A rule example like::
Rust
----
-This section shows how Frame support is added in Rust, using examples from the `SIP parser <https://github.com/OISF/suricata/blob/master/rust/src/sip/sip.rs>`_, and the `telnet parser <https://github.com/OISF/suricata/blob/master/rust/src/telnet/telnet.rs>`_.
+This section shows how Frame support is added in Rust, using examples from the `SIP parser <https://github.com/OISF/suricata/blob/main/rust/src/sip/sip.rs>`_, and the `telnet parser <https://github.com/OISF/suricata/blob/main/rust/src/telnet/telnet.rs>`_.
**Define the frame types**. The frame types are defined as an enum. In Rust, make sure to derive from the ``AppLayerFrameType``:
The Suricata source code contains an example plugin demonstrating how
to hook into some of these APIs. See
-https://github.com/OISF/suricata/blob/master/examples/plugins/c-custom-loggers/custom-logger.c.
+https://github.com/OISF/suricata/blob/main/examples/plugins/c-custom-loggers/custom-logger.c.
Packet Logging
~~~~~~~~~~~~~~
~~~~~~~~~~~~~~~~~~~~~~~~~
Application layer plugins can be added as demonstrated by example
-https://github.com/OISF/suricata/blob/master/examples/plugins/altemplate/
+https://github.com/OISF/suricata/blob/main/examples/plugins/altemplate/
The plugin code contains the same files as an application layer in the source tree:
- alname.rs : entry point of protocol with its registration
.. attention:: A pure rust plugin needs to be compiled with ``RUSTFLAGS=-Clink-args=-Wl,-undefined,dynamic_lookup``
This is because the plugin will link dynamically at runtime the functions defined in Suricata runtime.
-You can define this rust flag in a ``.cargo/config.toml`` file.
\ No newline at end of file
+You can define this rust flag in a ``.cargo/config.toml`` file.
.. note::
- Please have in mind that this is packaged from our latest development git master
+ Please have in mind that this is packaged from our latest development git main
and is therefore potentially unstable.
We do our best to make others aware of continuing development and items
Once parsed, Suricata rules are categorized for performance and further
processing (as different rule types will be handled by specific engine modules).
The signature types are defined in `src/detect.h
-<https://github.com/OISF/suricata/blob/master/src/detect.h>`_:
+<https://github.com/OISF/suricata/blob/main/src/detect.h>`_:
.. literalinclude:: ../../../src/detect.h
:caption: src/detect.h
This categorization is done taking into consideration the presence or absence of
certain rule elements, as well as the type of keywords used. The categorization
currently takes place in `src/detect-engine-build.c:void SignatureSetType()
-<https://github.com/OISF/suricata/blob/master/src/detect-engine-build.c#L1642-L1704>`_.
+<https://github.com/OISF/suricata/blob/main/src/detect-engine-build.c#L1642-L1704>`_.
The ``SignatureSetType()`` overall flow is described below:
--------------------
The `Action Scope` mentioned above relates to the Signature Properties, as seen in
-`src/detect-engine.c <https://github.com/OISF/suricata/blob/master/src/detect-engine.c>`_:
+`src/detect-engine.c <https://github.com/OISF/suricata/blob/main/src/detect-engine.c>`_:
.. literalinclude:: ../../../src/detect-engine.c
:caption: src/detect-engine.c
Signatures that inspect broken or invalid packets. They expose Suricata decoding
events.
-For more examples check https://github.com/OISF/suricata/blob/master/rules/decoder-events.rules.
+For more examples check https://github.com/OISF/suricata/blob/main/rules/decoder-events.rules.
Example
"""""""
Clients are implemented for some programming languages and can be used as code
example to write custom scripts:
-* Rust: https://github.com/OISF/suricata/blob/master/rust/suricatasc (version provided in Suricata 8+)
+* Rust: https://github.com/OISF/suricata/blob/main/rust/suricatasc (version provided in Suricata 8+)
* Python: https://github.com/OISF/suricata/blob/main-7.0.x/python/suricata/sc/suricatasc.py (Python version from older versions of Suricata)
* Perl: https://github.com/aflab/suricatac (a simple Perl client with interactive mode)
* C: https://github.com/regit/SuricataC (a Unix socket mode client in C without interactive mode)
Modify the Makefile to use `libsuricata-config`.
Before building this plugin you will need to build and install Suricata from the
-git master branch and install the development tools and headers:
+git main branch and install the development tools and headers:
- `make install-library`
- `make install-headers`
Modify the Makefile to use `libsuricata-config`.
Before building this plugin you will need to build and install Suricata from the
-git master branch and install the development tools and headers:
+git main branch and install the development tools and headers:
- `make install-library`
- `make install-headers`
projects / thirdparty / suricata.git / commitdiff
