208 lines
6.3 KiB
Plaintext
208 lines
6.3 KiB
Plaintext
= Rule Description
|
|
|
|
This document describes how `+rule.adoc+` and its dependencies should be structured.
|
|
|
|
See also the <<styling_guide.adoc#,Styling Guidelines>>.
|
|
|
|
== Sections
|
|
|
|
There should be no first level titles (`+= Title+`) in your adoc.
|
|
|
|
The following are the only allowed second level titles for H2:
|
|
|
|
include::section_names.adoc[]
|
|
|
|
Most third-level titles (`+=== Title t3+`) are not checked, the only type of rule description for which some of these
|
|
titles are checked are the progressive education rules (see below).
|
|
|
|
== Types of rule description
|
|
|
|
The above list of allowed H2 sections is an absolute list and covers all the different types of rule descriptions that exist.
|
|
However, depending on the type of rule description, the expected order and allowed sections are not the same.
|
|
There are currently 3 types of rule descriptions, each having a specific structure.
|
|
|
|
=== 1. Standard
|
|
|
|
The standard rule description is the currently most widespread format. It includes all _Code Smells_, _Bugs_ and most _Vulnerabilities_.
|
|
|
|
This is the "classical" format that starts with a description of the rule, and is usually followed by code examples of bad and good practices,
|
|
with some links to resources at the end.
|
|
|
|
This format has the structure of the following section:
|
|
|
|
. Description (no title)
|
|
. Noncompliant Code Example
|
|
. Compliant Solution
|
|
. Exceptions
|
|
. See
|
|
. See Also
|
|
|
|
Note that most sections are optional, only the description is mandatory.
|
|
|
|
=== 2. Hotspot
|
|
|
|
Specific to the _Hotspot_ issue type, this format is mostly similar to the standard one,
|
|
with the addition of 2 new sections: `Ask Yourself Whether` and `Recommended Secure Coding Practices`. Additionally, the `Noncompliant Code Example`
|
|
section has been renamed into `Sensitive Code Example`: this is based on the fact that for _Hotspots_ there is no certainty that what was raised
|
|
is an actual vulnerability.
|
|
|
|
The possible sections for this format are the following:
|
|
|
|
. Description (no title)
|
|
. Ask Yourself Whether
|
|
. Recommended Secure Coding Practices
|
|
. Sensitive Code Example
|
|
. Compliant Solution
|
|
. Exceptions
|
|
. See
|
|
. See Also
|
|
|
|
=== 3. Progressive Education
|
|
|
|
Finally, the last format is the one related to the effort done on Progressive Education.
|
|
This new format has a completely new structure, with additional subtitles and information,
|
|
so as to be as comprehensible as possible for the users.
|
|
|
|
This new structure is defined as follows:
|
|
|
|
. Short description (no title)
|
|
. Why is this an issue?
|
|
.. What is the potential impact?
|
|
. How to fix it?
|
|
.. How to fix it in `{Framework Display Name}`
|
|
.. How does this work?
|
|
.. Pitfalls
|
|
.. Going the extra mile
|
|
. Resources
|
|
.. Documentation
|
|
.. Articles & Blog Posts
|
|
.. Conference Presentations
|
|
.. Standards
|
|
|
|
Content of the section "_3. How to fix it?_" (i.e. subsections 3.a, 3.b, 3.c and 3.d) may be repeated multiple times, as
|
|
each repetition will represent the specific _How to fix it?_ section for a given framework.
|
|
For example:
|
|
....
|
|
== How to fix it?
|
|
|
|
=== How to fix it in Spring
|
|
... Some generic text and code examples for Spring...
|
|
|
|
=== How does this work?
|
|
... Explanation about how the exploit works in Spring...
|
|
|
|
=== Pitfalls
|
|
... Generic and Spring-specific pitfalls to avoid when fixing the issue...
|
|
|
|
=== How to fix it in JSP
|
|
... Some generic text and code examples for JSP...
|
|
|
|
=== How does this work?
|
|
... Explanation about how the exploit works in JSP...
|
|
|
|
=== Pitfalls
|
|
... Generic and JSP-specific pitfalls to avoid when fixing the issue...
|
|
....
|
|
|
|
Ideally, by convention and for maintainability, each framework _How to fix it?_ section will be defined in separate files.
|
|
Ex:
|
|
....
|
|
== How to fix it?
|
|
|
|
include::./how-to-fix-it/framework-1.adoc[]
|
|
|
|
include::./how-to-fix-it/framework-2.adoc[]
|
|
....
|
|
|
|
Note that each framework-specific _How to fix it?_ subsection must start with an H2 subtitle following the given format:
|
|
`How to fix it in (?:(?:an|a|the)\\s)?(.*)`.
|
|
This is important, as this format will be expected by the analyzers when loading the rule content to recognize the different subsections.
|
|
Furthermore, the display name of the framework has to match an allowed framework
|
|
display name, as defined in <<allowed_framework_names.adoc#,this allowed framework names file>>.
|
|
|
|
Finally, additional information regarding each of the sections and subsections present in the educational rule description
|
|
can be found https://docs.google.com/document/d/1caqBXTO1r7vftWrNXt_aNVe4rHcB5C6u6oKMBFjbzwo[in this document].
|
|
|
|
== Code Examples
|
|
|
|
Whenever possible, prefix your code blocks with `[source,language]`, in order to get syntax coloring.
|
|
|
|
....
|
|
[source,cpp]
|
|
----
|
|
int main(int argc, const char** argv) {
|
|
return 0;
|
|
}
|
|
----
|
|
....
|
|
|
|
That is mandatory for the Noncompliant and Compliant code example sections, just recommended - at the moment - for other sections.
|
|
|
|
The language names accepted are usually the name we already use for the language folders in RSPEC. Exceptions are:
|
|
|
|
cfamily:: use `cpp`, `c`, or `objectivec`
|
|
|
|
plsql:: use `sql`
|
|
|
|
tsql:: use `sql`
|
|
|
|
In case no language is appropriate for a code block (for example shared examples between multiple languages), you can use `text` as the language.
|
|
|
|
== Parameters
|
|
|
|
Parameters should be listed in a subsection as follow:
|
|
|
|
....
|
|
=== Parameters
|
|
|
|
.name
|
|
****
|
|
_TYPE_
|
|
|
|
----
|
|
default value
|
|
----
|
|
|
|
Description of what the parameter does.
|
|
****
|
|
|
|
.name2
|
|
****
|
|
----
|
|
another default value
|
|
----
|
|
Description of what this second parameter does.
|
|
****
|
|
|
|
.name3
|
|
****
|
|
_TYPE_
|
|
|
|
Description of what this third parameter does.
|
|
****
|
|
|
|
.name4
|
|
****
|
|
Description of what this fourth parameter does.
|
|
****
|
|
|
|
....
|
|
|
|
The parameter name and the description are mandatory. The type and default value are not.
|
|
|
|
The parameter name with a `.` before will be the title of the block below marked by `****`.
|
|
|
|
We always use `----` around the default parameter to avoid having a special character confuse AsciiDoctor and to create a visual consistency for all parameters.
|
|
|
|
== Comment a rule
|
|
|
|
Comments and links that were created on Jira have been gathered in a `comments-and-links.adoc` file for each concerned rule. +
|
|
You can add a comment anywhere in a rule by adding the following lines in the `*.adoc` file:
|
|
[source]
|
|
----
|
|
\ifdef::env-github,rspecator-view[]
|
|
John Doe (9 Jun 2021, 15:49): my comment on the rule
|
|
\endif::env-github,rspecator-view[]
|
|
----
|
|
This way, your comment will only be visible in GitHub preview and on the Search Page (and will not be visible for the user).
|