From 9932ca585e02eea72f03a798cf4b5527f4fdfb60 Mon Sep 17 00:00:00 2001 From: Micah Snyder Date: Thu, 15 Feb 2024 18:56:26 -0500 Subject: [PATCH] Remove bugzilla references, replacing bugzilla links with better documentation --- src/manual/Development/Contribute.md | 2 +- .../Development/clamav-git-work-flow.md | 2 +- src/manual/Development/personal-forks.md | 5 ++-- src/manual/Signatures/BodySignatureFormat.md | 26 ++++++++++++++++--- src/manual/Signatures/LogicalSignatures.md | 2 +- src/manual/Usage/ReportABug.md | 2 -- 6 files changed, 28 insertions(+), 11 deletions(-) diff --git a/src/manual/Development/Contribute.md b/src/manual/Development/Contribute.md index c663fb4..6335091 100644 --- a/src/manual/Development/Contribute.md +++ b/src/manual/Development/Contribute.md @@ -24,7 +24,7 @@ For ClamAV documentation projects, submit pull-requests to: fork and appear as pull requests from the fork to the upstream `clamav` repository. +A branch for working a JIRA task or GitHub issue. These are typically only found in a personal > fork and appear as pull requests from the fork to the upstream `clamav` repository. diff --git a/src/manual/Development/personal-forks.md b/src/manual/Development/personal-forks.md index 57c395d..a315a46 100644 --- a/src/manual/Development/personal-forks.md +++ b/src/manual/Development/personal-forks.md @@ -41,9 +41,8 @@ git clone cd clamav-YourNameHere ``` -Create a branch off of the default branch where you will work. If working on a GitHub Issue, Bugzilla Bug, or JIRA task`*`, the following branch name prefixes will help you and others identify the branch: -- For GitHub Issues: `issue-####-short-description` -- For Bugzilla Bugs: `bb-####-short-description` +Create a branch off of the default branch where you will work. If working on a GitHub Issue, or JIRA task`*`, the following branch name prefixes will help you and others identify the branch: +- For GitHub issues: `issue-####-short-description` - For JIRA task: `CLAM-####-short-description` > _Note_: `*`The ClamAV JIRA task tracker is not accessible outside of the Cisco network. diff --git a/src/manual/Signatures/BodySignatureFormat.md b/src/manual/Signatures/BodySignatureFormat.md index 23e1fbb..8156f77 100644 --- a/src/manual/Signatures/BodySignatureFormat.md +++ b/src/manual/Signatures/BodySignatureFormat.md @@ -50,10 +50,30 @@ ClamAV supports the following wildcards for hex-signatures: - `HEXSIG[x-y]aa` or `aa[x-y]HEXSIG` - Match `aa` anchored to a hex-signature, see [Bugzilla ticket 776](https://bugzilla.clamav.net/show_bug.cgi?id=776) for discussion and - examples. + The `[x-y]` notation enables matching on a range of any bytes where one side is just a single-byte (two nibbles), represented by "`aa`". The other side, represented by "HEXSIG" must be at least 2 bytes (4 nibbles). -The range signatures `*` and `{}` virtually separate a hex-signature into two parts, eg. `aabbcc*bbaacc` is treated as two sub-signatures `aabbcc` and `bbaacc` with any number of bytes between them. It’s a requirement that each sub-signature includes a block of two static characters somewhere in its body. Note that there is one exception to this restriction; that is when the range wildcard is of the form `{n}` with `n<128`. In this case, ClamAV uses an optimization and translates `{n}` to the string consisting of `n ??` character wildcards. Character wildcards do not divide hex signatures into two parts and so the two static character requirement does not apply. + The similar notation `{n-m}` requires that both sides have at least 2 bytes. The difference here is that [x-y] enables matching of just one byte. + + A second, unfortunate, difference is that `y` cannot be greater than 32. + + Example logical signature: + ``` + testsig;Target:0;0;64[4-4]61616161{2}6262[3-6]65:27 + ``` + + In the example signature "testsig", there are two examples of this wildcard variant: + 1. `64[4-4]61616161`: This will search for the byte "64" followed by the hex sequence "61616161" with exactly 4 arbitrary bytes in between. + + 2. `6262[3-6]65`: This will search for the hex sequence "6262" followed by the byte "65" with 3 to 6 arbitrary bytes in between. + + (Note that the "{2}" in between is the other wildcard variant meaning to match 2 arbitrary bytes.) + + Thus the signature matches many variations such as these. Braces and brackets are added in this hex to illustrate the boundaries of the wildcard matches: + - `64[61616161]616161616{4646}6262[0102]65` + - `64[67676767]616161616{0102}6262[262626]65` + - `64[00000000]616161616{9696}6262[26262636]65` + +The range signatures `*` and `{}` virtually separate a hex-signature into two parts, eg. `aabbcc*bbaacc` is treated as two sub-signatures `aabbcc` and `bbaacc` with any number of bytes between them. It’s a requirement that each sub-signature includes a block of two static characters somewhere in its body. Note that there is one exception to this restriction; that is when the range wildcard is of the form `{n}` with `n<128`. In this case, ClamAV uses an optimization and translates `{n}` to the string consisting of `n` number of `??` character wildcards. Character wildcards do not divide hex signatures into two parts and so the two static character requirement does not apply. ## Character classes diff --git a/src/manual/Signatures/LogicalSignatures.md b/src/manual/Signatures/LogicalSignatures.md index 6cb0665..64ed18e 100644 --- a/src/manual/Signatures/LogicalSignatures.md +++ b/src/manual/Signatures/LogicalSignatures.md @@ -178,7 +178,7 @@ TestMacro;Engine:51-255,Target:0;0;616161{3-4}(626262|636363) - In the example, `{min-max}` is `{6-7}` and it is relative to the start of a `616161` match. -- For more information and examples please see . +The intention with macro subsignatures is to ease the burden of writing signatures for scenarios like this... A small number of logical signatures may be created that target a given phishing email. Macro signatures are created for variations in the email, such as variations of URL domains. In this way, new macro signatures can be added to account for additional variations in the phishing URLs without updating the larger logical signature, and without adding all new logical signatures. ### Byte Compare Subsignatures diff --git a/src/manual/Usage/ReportABug.md b/src/manual/Usage/ReportABug.md index 847273d..671cf62 100644 --- a/src/manual/Usage/ReportABug.md +++ b/src/manual/Usage/ReportABug.md @@ -14,8 +14,6 @@ If you find a bug in ClamAV, please do the following before you submit a bug rep 2. Review [the open issues](https://github.com/Cisco-Talos/clamav/issues?q=is%3Aopen+is%3Aissue) to make sure someone else hasn't already reported the same issue. - > _Tip_: Before switching to GitHub Issues, ClamAV used Bugzilla. You can also review [older open tickets from the Bugzilla archive](https://bugzilla.clamav.net/buglist.cgi?bug_status=UNCONFIRMED&bug_status=NEW&bug_status=ASSIGNED&bug_status=NEEDINFO&bug_status=REOPENED&classification=ClamAV&limit=0&list_id=162358&order=changeddate%20DESC%2Cbug_status%2Cpriority%2Cassigned_to%2Cbug_id&product=ClamAV&query_format=advanced&resolution=---). - 3. Collect the required information, described below, to include with your report. 4. Create a [new ticket on GitHub](https://github.com/Cisco-Talos/clamav/issues/new).