docs: update messages

rules/go/gosec/blocklist/cgi.yml

@@ -12,17 +12,47 @@ metadata:
   remediation_message: |
     ## Description
 
-    It's not recommended to use `net/http/cgi` package.
-    Go versions < 1.6.3 are vulnerable to Httpoxy attack: (CVE-2016-5386).
+    Using the `net/http/cgi` package in Go, especially with versions prior to 1.6.3, exposes the application to the Httpoxy attack, a vulnerability identified as CVE-2016-5386. This vulnerability arises from the way CGI and FastCGI protocols handle certain environment variables, which can be manipulated to intercept and redirect outgoing HTTP requests made by the web application.
 
     ## Remediations
 
-    ❌ Avoid using `net/http/cgi`:
+    ✅ Update Go Version
+
+    Ensure you are using a version of Go that is 1.6.3 or later, where this vulnerability is patched.
+
+    ```sh
+    # Check Go version and update if necessary
+    go version
+    # Follow Go's update instructions if your version is < 1.6.3
+    ```
+
+    ✅ Use Alternative Packages
+
+    Refrain from using CGI where possible. Utilize alternative packages and methods to handle HTTP requests which do not rely on the CGI protocol.
+
+    ```go
+    // Use the standard net/http package instead
+    import "net/http"
+    ```
+
+    ❌ Don't Use `net/http/cgi` in Older Versions
+
+    Do not use the `net/http/cgi` package if you are operating on Go versions older than 1.6.3 as they are susceptible to the Httpoxy vulnerability.
 
     ```go
+    // This import is vulnerable to Httpoxy in Go < 1.6.3
     import "net/http/cgi"
     ```
 
+    ❌ Avoid Exposing Environment Variables
+
+    Ensure that the environment variables such as `HTTP_PROXY` are not being exposed unintentionally, as this can be leveraged for Httpoxy attacks.
+
+    ## Resources
+
+    - [CVE-2016-5386 Detail](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2016-5386)
+    - [Httpoxy.org](https://httpoxy.org/)
+
   cwe_id:
     - 327
   id: go_gosec_blocklist_cgi

rules/go/gosec/blocklist/des.yml

@@ -12,46 +12,48 @@ metadata:
   remediation_message: |
     ## Description
 
-    The DES algorithm has not been recommended for over 15 years and was withdrawn from NIST (FIPS 46-3) in 2005.
+    The Data Encryption Standard (DES) is an outdated symmetric-key algorithm for encryption. Officially deemed insecure and no longer recommended for use, DES was withdrawn by the National Institute of Standards and Technology (NIST) as a standard in 2005, primarily because of its 56-bit key size, which is vulnerable to brute-force attacks.
 
     ## Remediation
 
-    It is recommended that an algorithm that provides message integrity be used instead.
+    To ensure the confidentiality and integrity of sensitive data, it is crucial to utilize a modern and secure encryption algorithm. The use of Advanced Encryption Standard (AES) with a key size of 256 bits (AES-256) is recommended for its strong security properties and widespread acceptance as a replacement for DES.
 
-    ✅ Prefer the usage of `AES-256`:
+    ✅ Implement AES-256 for Strong Encryption
 
     ```go
-    // 32 byte keys will configure AES-256
+    // Use AES-256 for secure encryption by initializing a 32-byte key for AES-256
     key := make([]byte, 32)
     if _, err := io.ReadFull(rand.Reader, key); err != nil {
       log.Fatal(err)
     }
 
+    // Create a new cipher block from the key
     blockCipher, err := aes.NewCipher(key)
     if err != nil {
       log.Fatal(err)
     }
 
+    // Use Galois/Counter Mode (GCM) for both encryption and decryption
     aead, err := cipher.NewGCM(blockCipher)
     if err != nil {
       log.Fatal(err)
     }
 
     var encrypted = []byte{}
     var nonce = []byte{}
-    // Encryption routine
+
+    // Encrypt a message with AES-256 using GCM
     {
       msg := []byte("Some secret message")
-      // note that the key must be rotated every 2^32 random nonces used otherwise
-      // cipher text could be repeated
+      // Ensure nonces are unique for each encryption to maintain security
       nonce = make([]byte, 12)
       if _, err := io.ReadFull(rand.Reader, nonce); err != nil {
         log.Fatal(err)
       }
       encrypted = aead.Seal(nil, nonce, msg, nil)
     }
 
-    // Decryption routine
+    // Decrypt the message securely
     {
       msg, err := aead.Open(nil, nonce, encrypted, nil)
       if err != nil {
@@ -61,6 +63,14 @@ metadata:
     }
     ```
 
+    ❌ Do Not Use Deprecated Algorithms
+    Avoid using deprecated cryptographic algorithms such as DES, as they do not provide adequate security against modern threats and attacks.
+
+    ## Resources
+
+    - [NIST Recommendations](https://csrc.nist.gov/publications/detail/sp/800-131a/rev-2/final)
+    - [AES-256 Encryption](https://en.wikipedia.org/wiki/Advanced_Encryption_Standard)
+
   cwe_id:
     - 327
   id: go_gosec_blocklist_des

rules/go/gosec/blocklist/md5.yml

@@ -12,13 +12,16 @@ metadata:
   remediation_message: |
     ## Description
 
-    The MD5 message-digest algorithm has been cryptographically broken and is unsuitable for further use. The MD5 hash algorithm has been found to be vulnerable to producing collisions. This means that two different values, when hashed, can lead to the same hash value.
+    MD5 is a widely used cryptographic hash function that produces a 128-bit (16-byte) hash value. It's commonly used to check the integrity of files. However, MD5 is not collision-resistant; this means that different inputs may produce the same output hash. MD5's vulnerabilities and the feasibility of collision attacks have rendered it obsolete for security-related purposes, particularly digital signatures, SSL certificates, and cryptographic message authentication.
 
-    ## Remediations
+    ## Remediation
 
-    ✅ It is recommended that the SHA-3 or BLAKE2 family of algorithms be used for non-password based cryptographic hashes instead.
+    Given the vulnerabilities of MD5, it is highly recommended to switch to more secure hashing algorithms. For hashing purposes that do not involve passwords, such as verifying file integrity or generating unique identifiers, SHA-3 or BLAKE2 can be used due to their stronger cryptographic properties.
+
+    ✅ Use SHA-3 or BLAKE2 for General Hashing Needs
 
     ```go
+    // BLAKE2 is a cryptographic hash function faster than MD5, SHA-1, and SHA-2, and as secure as the latest standard SHA-3
     fileContents := []byte("some file contents to create hash for")
     blake2bHasher, err := blake2b.New512(nil)
     if err != nil {
@@ -28,9 +31,14 @@ metadata:
     fmt.Printf("%s\n", hex.EncodeToString(hashedValue))
     ```
 
-    ✅ For password based cryptographic hashes, consider using the bcrypt or Argon2id family of cryptographic hashes.
+    For password hashing, where the hash functions need to be slow to combat brute-force attacks, bcrypt or Argon2id should be used. These algorithms are designed to be computationally intensive to hash and verify, which helps protect against password cracking attempts.
+
+    ✅ Adopt bcrypt or Argon2id for Password Hashing
+
+    The bcrypt algorithm is a good choice for password hashing as it allows you to adjust the cost (computational complexity) and is widely supported. Argon2id is the winner of the Password Hashing Competition and offers a good balance between resistance to GPU cracking attacks and usability.
 
     ## Resources
+
     - [OWASP Password Storage Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Password_Storage_Cheat_Sheet.html)
 
   cwe_id:

rules/go/gosec/blocklist/rc4.yml

@@ -12,16 +12,16 @@ metadata:
   remediation_message: |
     ## Description
 
-    The RC4 stream-cipher has been cryptographically broken and is unsuitable for use in production.
+    RC4 is a stream cipher that was once popular for its simplicity and speed in operation. However, extensive research over the years has revealed multiple vulnerabilities, rendering RC4 insecure in most contexts. Its weaknesses in key scheduling and the generation of non-random bytes have led to successful cryptanalysis and practical attacks, making it unsuitable for securing data.
 
-    ## Remediations
+    ## Remediation
 
-    It is recommended that Advanced Encryption Standard (AES) be used instead.
+    With the known vulnerabilities of RC4, it's essential to move to a more secure cipher. AES (Advanced Encryption Standard) is the recommended replacement because it has undergone extensive scrutiny and is considered secure against cryptanalysis.
 
-    ✅ Consider using `AES-256`
+    ✅ Switch to AES-256 for Robust Encryption
 
     ```go
-    // 32 byte keys will configure AES-256
+    // 32 byte keys will set up AES-256, which is a secure block cipher that has become the industry standard for encryption.
     key := make([]byte, 32)
     if _, err := io.ReadFull(rand.Reader, key); err != nil {
       log.Fatal(err)
@@ -42,8 +42,7 @@ metadata:
     // Encryption routine
     {
       msg := []byte("Some secret message")
-      // note that the key must be rotated every 2^32 random nonces used otherwise
-      // cipher text could be repeated
+      // Note that the key must be rotated after every 2^32 uses of a single nonce-value to avoid cipher text repetition.
       nonce = make([]byte, 12)
       if _, err := io.ReadFull(rand.Reader, nonce); err != nil {
         log.Fatal(err)
@@ -61,6 +60,11 @@ metadata:
     }
     ```
 
+    Using AES-256 ensures that your encryption mechanism meets current security standards and is robust against known attacks. AES has been widely adopted across various industries and has proven its reliability over time.
+
+    ## Resources
+
+    - [NIST Guidelines on Cryptography](https://csrc.nist.gov/publications/detail/sp/800-38a/final)
   cwe_id:
     - 327
   id: go_gosec_blocklist_rc4

rules/go/gosec/blocklist/sha1.yml

@@ -12,52 +12,30 @@ metadata:
   remediation_message: |
     ## Description
 
-    The SHA-1 message-digest algorithm has been cryptographically broken and is unsuitable for further use.
+    The SHA-1 hashing algorithm is no longer considered secure against well-funded attackers. It is vulnerable to collision attacks, which means it's possible to generate two different inputs that result in the same SHA-1 hash, undermining the hash's uniqueness and security. Due to these vulnerabilities, it is advised to discontinue using SHA-1 for cryptographic security.
 
-    ## Remediations
+    ## Remediation
 
-    It is recommended that the SHA-3, or BLAKE2 family of algorithms be used for non-password based cryptographic hashes instead. For password based cryptographic hashes, consider using the bcrypt or Argon2id family of cryptographic hashes.
+    When choosing a hashing algorithm for cryptographic purposes, it's important to select one that is resistant to collisions and other attack vectors. SHA-3 and BLAKE2 are both excellent choices for non-password-based hashing requirements due to their strong cryptographic properties.
 
-    ```go
-    // 32 byte keys will configure AES-256
-    key := make([]byte, 32)
-    if _, err := io.ReadFull(rand.Reader, key); err != nil {
-      log.Fatal(err)
-    }
+    ✅ For General Hashing Needs, Use SHA-3 or BLAKE2
 
-    blockCipher, err := aes.NewCipher(key)
-    if err != nil {
-      log.Fatal(err)
-    }
+    Choose SHA-3 or BLAKE2 for their resistance to known hash attack vectors, ensuring the integrity and uniqueness of your data fingerprints.
 
-    aead, err := cipher.NewGCM(blockCipher)
-    if err != nil {
-      log.Fatal(err)
-    }
+    ✅ For Password Hashing, Prefer bcrypt or Argon2id
 
-    var encrypted = []byte{}
-    var nonce = []byte{}
-    // Encryption routine
-    {
-      msg := []byte("Some secret message")
-      // note that the key must be rotated every 2^32 random nonces used otherwise
-      // cipher text could be repeated
-      nonce = make([]byte, 12)
-      if _, err := io.ReadFull(rand.Reader, nonce); err != nil {
-        log.Fatal(err)
-      }
-      encrypted = aead.Seal(nil, nonce, msg, nil)
-    }
+    For password hashing specifically, bcrypt or Argon2id are recommended. These algorithms are designed to be computationally intensive, which helps protect against brute-force attacks.
 
-    // Decryption routine
-    {
-      msg, err := aead.Open(nil, nonce, encrypted, nil)
-      if err != nil {
-        log.Fatal(err)
-      }
-      fmt.Printf("Decrypted: %s\n", msg)
-    }
-    ```
+    ❌ Discontinue Using SHA-1 for Security Purposes
+
+    Given its vulnerabilities, avoid using SHA-1 in any security context to prevent potential collision attacks.
+
+    The code snippet provided is unrelated to the hashing algorithms and seems to be a continuation of the previous examples for encryption with AES-256. Ensure your hashing and encryption strategies are correctly implemented as per their intended use-cases.
+
+    ## Resources
+
+    - [OWASP Cryptographic Storage Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Cryptographic_Storage_Cheat_Sheet.html)
+    - [NIST Policy on Hash Functions](https://csrc.nist.gov/projects/hash-functions)
 
   cwe_id:
     - 327

rules/go/gosec/crypto/bad_tls_settings.yml

@@ -42,62 +42,35 @@ metadata:
   remediation_message: |
     ## Description
 
-    Usage of a cryptographically insecure cipher suite has been detected.
+    A security concern arises when a cryptographically insecure cipher suite is used in an application. Such cipher suites may be vulnerable to various types of attacks, reducing the security of the communication channel.
 
-    ## Remediations
+    ## Remediation
 
-    ✅ It is recommended that alternative ciphers be used instead.
+    To enhance the security of TLS connections, it is crucial to use up-to-date and secure cipher suites and protocols. Here are the recommended steps to ensure the use of secure ciphers:
 
-    ✅ It is strongly recommended that all TLS connections use TLS 1.3
+    ✅ Use Modern, Secure Cipher Suites
 
-    Go will automatically choose the most secure cipher when negotiating the TLS handshake with client or servers. TLS 1.3 cipher suites are configured to require Perfect
-    Forward Secrecy (PFS).
-    PFS is an important property as it will ensure that past encrypted transmissions could not be
-    decrypted if the TLS certificate was compromised.
+    Select cipher suites that are known to be secure and have properties such as Perfect Forward Secrecy (PFS), which protects past communications even if future private keys are compromised.
 
-    ```go
-    cert, err := tls.LoadX509KeyPair("server.crt", "server.key")
-    if err != nil {
-      log.Fatal(err)
-    }
+    ✅ Adopt TLS 1.3 Where Possible
 
-    cfg := &tls.Config{Certificates: []tls.Certificate{cert}, MinVersion: tls.VersionTLS13}
-    srv := &http.Server{
-      Addr:         ":8999",
-      TLSConfig:    cfg,
-      ReadTimeout:  time.Minute,
-      WriteTimeout: time.Minute,
-    }
-    log.Fatal(srv.ListenAndServeTLS("", ""))
-    ```
+    TLS 1.3 should be the preferred protocol as it includes improvements over previous versions, making it more secure against various attacks. Go's standard library will automatically prefer the most secure protocol and cipher suite available during the TLS handshake.
 
-    If TLS 1.0-1.2 must be used, then the following list of ciphers should be chosen as they
-    support
-    Perfect Forward Secrecy (PFS):
+    ✅ Configure TLS Properly If Using TLS 1.0-1.2
 
-    - TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
-    - TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
-    - TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
-    - TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
-    - TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305
-    - TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305
+    In cases where TLS 1.3 is not an option and you must use TLS 1.0-1.2, ensure to configure the cipher suites to use those that support PFS, as listed below.
 
+    ❌ Avoid Using Obsolete or Insecure Cipher Suites
 
-    Example `tls.Config` using the recommended cipher suites:
+    Avoid any cipher suites that do not support modern security standards, including those without PFS or with known vulnerabilities.
 
-    ```go
-    cfg := &tls.Config{
-        MinVersion: tls.VersionTLS12,
-        CipherSuites: []uint16{
-            tls.TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,
-            tls.TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,
-            tls.TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,
-            tls.TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,
-            tls.TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305,
-            tls.TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305,
-        },
-    }
-    ```
+    The provided Go code examples demonstrate how to configure the `tls.Config` struct for a Go server to use TLS 1.3 or to specify a list of secure cipher suites when using TLS 1.0-1.2.
+
+    ## Resources
+
+    - [Mozilla's SSL Configuration Generator](https://ssl-config.mozilla.org/)
+    - [OWASP TLS Cipher String Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/TLS_Cipher_String_Cheat_Sheet.html)
+    - [RFC 8446 - The Transport Layer Security (TLS) Protocol Version 1.3](https://tools.ietf.org/html/rfc8446)
 
   cwe_id:
     - 327