While traditional code comments focus on explaining the code's functionality, security-focused comments are crucial to promoting secure coding practices throughout the development lifecycle (SDLC). 

By making this simple tactic part of your natural workflow, you can assert your knowledge and become a security champion. Let's explore how integrating security comments into your code can benefit you and the security team.

Leading Forward Using Secure Code Comments 

Integrating security into your daily coding isn't just about ticking requirement boxes; it's about building a security mindset that makes you indispensable.

Secure-code comments are low-hanging fruit for sharing knowledge, learning from others, and making security a seamless part of your day. Senior developers and application security champions can quickly and effectively educate other developers about best practices without leaving the comfort of their Integrated Development Environment (IDE).

Best practice for code comments suggests emphasizing the why, not the what. Security-focused comments are no different. Meanwhile, they play a crucial role in promoting secure coding practices, enabling teams to:

• Explain Key Security Moves: Share the rationale behind specific security measures, such as input validation, encryption, and access control mechanisms.
• Flag Red Flags: Spot potential weaknesses in your code, like SQL injection, cross-site scripting (XSS), and unprotected data.
• Share Knowledge: Link to relevant security standards, guidelines, and resources and facilitate efficient code reviews.

Enhancing Code with Security Comments–Two Examples

Example 1: Preventing SQL Injection with Parameterized Queries (Python)

Let’s consider a simplified Python function, which performs a simple insert operation into a database:

def insert_user(conn, name, email):

  """
  Inserts a new user into the 'user' table.

  Args:

    conn: A sqlite3 connection object.

    name: The name of the user.

    email: The email address of the user.

  Returns:

    None


  This function uses a parameterized query to prevent SQL injection vulnerabilities. See: CWE-89 https://cwe.mitre.org/data/definitions/89.html

  By using placeholders (e.g., `?`) and passing the actual values as separate arguments,

  we avoid direct string concatenation. This ensures that user-supplied input cannot

  be manipulated to modify SQL commands.

  """

  sql = """INSERT INTO user (name, email) VALUES (?, ?)"""

  cur = conn.cursor()

  cur.execute(sql, (name, email))

  conn.commit()

  cur.close()

As you can see, in addition to the regular docstring, we succinctly mention why we’re using parameterized queries over string concatenation. We also reference a CWE and provide a link for anyone who wants to learn more. 

With just three extra sentences in a function comment, we’ve given less experienced developers who are code spelunking a quick lesson (or reminder) about why and how to prevent SQL injection.

Example 2:  Mitigating XSS Vulnerabilities with DOMPurify (React)

Let’s take a look at another example, this time on a React frontend. Here, we’re knowingly doing something potentially dangerous but effectively communicating to other developers the mitigations applied.

/**

 * Displays user-generated HTML content, sanitizing it with DOMPurify to prevent XSS vulnerabilities.

 *

 * This component uses `dangerouslySetInnerHTML` because the content being displayed *must* include HTML markup.

 * Alternatives like rendering plain text or using a limited subset of HTML tags are not sufficient for this use case. See: https://kanban.system/t/123 

 * **Security Considerations:**

 *

 * **CWE-79 (Improper Neutralization of Special Elements used in an HTML Page): https://cwe.mitre.org/data/definitions/79.html 

 * This code directly addresses CWE-79 by sanitizing the user-provided HTML before rendering it.  Without sanitization, malicious

 *     users could inject JavaScript code that would be executed in the context of the website, leading to

 *     XSS attacks.

 * *   **Why not just use textContent?**  If we used `textContent` or similar methods, any HTML tags in the user

 *     input would be treated as plain text and displayed as-is.  This would prevent XSS, but it would

 *     also defeat the purpose of allowing users to input HTML in the first place.

 * *   **Why DOMPurify?**  DOMPurify is a widely used and well-maintained library specifically designed for

 *     sanitizing HTML. It's more robust and secure than attempting to create a custom sanitization

 *     solution.  It handles a wide range of potential XSS attack vectors.

 *

 * @param {string} htmlContent The user-generated HTML content.  This is assumed to be untrusted.

 * @returns {JSX.Element} The sanitized HTML rendered within a div.

 */

function SafeHTMLDisplay({ htmlContent }) {

  const sanitizedHTML = DOMPurify.sanitize(htmlContent);

  return (

    <div dangerouslySetInnerHTML={{ __html: sanitizedHTML }} />

  );

}

This time we go into more detail about the why. Let’s break it down: 

First, it’s important to acknowledge that the original approach isn’t best practice. Second, you can level up developer awareness about alternative options.Then, connect the dots for maximum impact, sharing why this approach is required to satisfy product requirements. Finally, it’s important to detail security considerations with CWE IDs, codifying the weakness you’re proactively mitigating; yes, you can even justify the introduction of another dependency compared to a custom implementation.

Any future developer tasked with modifying the comment feature will quickly understand the importance of keeping this mitigation rather than “cleaning up the code” because it still functions “the same” without it. As an AppSec developer or security champion, you’ve just avoided another security report being raised because of a regression introduced by an over-eager junior developer. It's well worth the 15 lines of extra code.

Even better, any security engineer performing a secure code review will be much more confident that their developer understands why they wrote the code the way they did. This knowledge, in turn, expedites that coveted ‘approve’ on their pull request, reducing the time to get the code safely into production. 

Identifying and codifying vulnerabilities with Find the Flaw

Setting the tone with security-focused comments largely falls to the lead developer or security champion, presenting an easy opportunity for aspiring champions to stand out. Remember, the goal is to identify and codify weaknesses in code before or as it is being written; this approach ensures others can craft easy-to-understand security comments too.

Whether you’re just starting out or looking to grow your skillset, Immersive AppSec’s Find the Flaw collections provide ample opportunities to build critical DevSecOps muscle memory. You’ll learn to identify various common vulnerabilities in code and recognize what CWE IDs they correspond to. Writing security-focused comments will feel like second nature when you're coding up a storm!

Beyond Code Comments: Empowering Your Manager to Recognize the Power of AppSec Training

Code comments are a valuable AppSec tool, albeit only one piece of the puzzle. To cultivate a developer-led security culture, organizations need managers who recognize the power of comprehensive training programs for their elite developers. These programs support proactive developers with the knowledge and skills to build secure applications from the ground up. As a result, the organization achieves development velocity SLAs and application security simultaneously.

Remember to share your experience learning by doing, gaining the attackers’ perspective, which Immersive Labs AppSec offers. Your manager and teammates should recognize the value of using safe, real-world scenarios and interactive exercises, such that the training you do (now) targets the problems you have (now). 

Share your thoughts

Check out this Find the Flaw collection and then share your thoughts with The Human Connection community: 

For developers: Does adding security rationale to your comments feel like an ‘easy enough' lift?

For security champions: Are you already using this technique or something similar? How have you convinced other developers to adopt this style of commenting?