docs: properly ignore bandit warnings (#623)

* docs: adding documentation on how to properly ignore bandit warnings

* fix: typo

* fix: vale issues

* Update doc/source/how-to/vulnerabilities.rst

Co-authored-by: Maxime Rey <[email protected]>

* docs: adding warning section

* fix: adding extra space

* Update doc/source/how-to/vulnerabilities.rst

Co-authored-by: Revathy Venugopal <[email protected]>

---------

Co-authored-by: Maxime Rey <[email protected]>
Co-authored-by: Revathy Venugopal <[email protected]>

Author: 3 people

doc/source/how-to/vulnerabilities.rst

@@ -204,6 +204,13 @@ and the risk of command injection is significantly reduced.
           # Removing shell=True and using a list
           subprocess.run(["echo", user_input])  # User input is not executed as a shell command
 
+.. note::
+
+  Bandit warning remains even after deactivating the `shell=True` argument.
+  If you are sure that the command is safe, you can ignore the Bandit warning. Please
+  check the `Ignore Bandit warnings`_ section for more information on how to do so.
+
+
 
 **try except continue statements**
 
@@ -285,3 +292,43 @@ provides a secure way to generate random numbers.
 
           secure_random_number = secrets.randbelow(100)  # Secure random number generation
           secure_random_letter = secrets.choice(["a", "b", "c"])  # Secure choice from a list
+
+
+Ignore Bandit warnings
+----------------------
+
+In-line comment
+~~~~~~~~~~~~~~~
+
+When using Bandit, you may encounter warnings that you believe are not relevant to your codebase
+or that you have already addressed. In such cases, you can ignore specific Bandit warnings by
+adding a comment to the end of the line that triggers the warning. The comment should be in the
+format ``# nosec <warning_id>``, where ``<warning_id>`` is the ID of the warning you want to ignore.
+
+When you ignore a Bandit warning, it is essential to provide a clear comment explaining why
+the warning is being ignored. This helps maintainers and other developers understand the context
+and rationale behind the decision.
+
+For example, to ignore the B404 warning, you would add `# nosec B404` to the end of the line:
+
+.. code:: python
+
+  # Subprocess is needed to start the backend. But
+  # the input is controlled by the library. Excluding bandit check.
+  import subprocess  # nosec B404
+
+
+.. warning::
+
+  Please note that ignoring Bandit warnings should be done with caution, and you should ensure
+  that the code is safe and does not introduce any security risks. It is recommended to review the
+  `bandit documentation`_ for more information on each warning and the potential risks involved.
+
+
+Security considerations file
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In addition to ignoring specific Bandit warnings, it is a good practice to document the ignored
+advisories in a dedicated file. You can find an example of such a file in the `PyACP security
+considerations`_ documentation page. This way, you can provide to the users a clear overview of
+the vulnerabilities that need to be taken into account when using the library.

doc/source/links.rst

@@ -118,6 +118,7 @@
 .. _unzip: https://7-zip.org/
 .. _conventional_commit_types: https://github.com/commitizen/conventional-commit-types/blob/master/index.json
 .. _Test Driven Development (TDD): https://en.wikipedia.org/wiki/Test-driven_development
+.. _bandit documentation: https://bandit.readthedocs.io/en/latest/
 .. _blacklists bandit documentation: https://bandit.readthedocs.io/en/latest/blacklists/blacklist_calls.html
 
 .. #Sphinx-related links

doc/styles/config/vocabularies/ANSYS/accept.txt

@@ -56,6 +56,7 @@ Microelectromechanical
 monospaced
 Muela
 [Nn]amespace
+nosec
 npm
 numpy
 [Nn]umpydoc