🔖 Introduction
About the project
The Ballerina Scan Tool is a static security analysis feature built directly into the Ballerina compiler. In the modern software landscape, security is not an afterthought but a critical component of the development lifecycle ("shifting left"). I created this tool to provide Ballerina developers with a seamless, powerful way to detect potential security vulnerabilities directly within their existing workflow. By integrating it into the compiler, the tool analyzes source code for common security flaws like hardcoded secrets and SQL injection risks during the build process itself. The result is a frictionless security audit that helps developers write more secure, reliable code from the very beginning.
[Image: The Ballerina logo next to a security shield icon.]
🤔 Problem space
Problems to Solve/Requirements to Create
Ballerina developers, like developers in any language, need an automated and reliable way to identify security vulnerabilities before code is deployed. Relying on manual reviews or external, often complex, security tools creates friction and can let critical issues slip through to production.
👉 Problem: Security Vulnerabilities are Often Detected Too Late
Common security flaws such as SQL injection, path traversal, hardcoded secrets, and insecure use of APIs are frequently missed during manual code reviews. When these issues are discovered later in the development cycle (e.g., during QA or by a dedicated security team), they are significantly more expensive and time-consuming to fix. In the worst-case scenario, they are discovered in production after a security breach.
Current solution
Without an integrated tool, developers rely on a combination of solutions:
Manual Peer Reviews: Relying on security-conscious team members to spot vulnerabilities, which is inconsistent and not scalable.
External SAST Tools: Using third-party Static Application Security Testing (SAST) tools that require separate configuration, licensing, and integration into the CI/CD pipeline, adding complexity and slowing down development.
[📸 A code snippet showing a Ballerina function with a clear SQL injection vulnerability, where user input is directly concatenated into a database query string.]
How do we know it is a problem?
Industry-wide data from sources like the OWASP Top 10 consistently shows that these types of vulnerabilities remain the most common causes of security breaches. The high cost of post-deployment bug fixes is a well-documented metric in software engineering, with security flaws being among the most critical and expensive.
Goals
Company objective 🎯
To provide a secure-by-default development experience for Ballerina users, empowering them to build robust and reliable network applications with confidence.
Project goals
Project goal: Integrate a powerful static security analysis engine directly into the Ballerina compiler to make security scanning a default part of the build process.
Project goal: Detect a comprehensive set of common security vulnerabilities, including SQL injection, path traversal, hardcoded secrets, and insecure API usage.
Project goal: Provide clear, actionable diagnostics that pinpoint the exact location of a vulnerability and explain the potential risk, enabling developers to fix issues quickly.
User Stories
👤 Ballerina Developer
A software developer building services and integrations with Ballerina. Their primary focus is on delivering functionality while adhering to security best practices.
Goals: Write secure code without needing to be a security expert; get immediate feedback on potential vulnerabilities; ensure code passes security checks in the CI pipeline.
Needs: Automated security scanning that requires zero configuration; clear error messages integrated into their build output and IDE.
👤 DevOps/Security Engineer
An engineer responsible for maintaining the security and integrity of the CI/CD pipeline and production environments.
Goals: Enforce security policies automatically; prevent vulnerable code from being deployed; generate security reports for compliance and auditing.
Needs: A tool that can be easily integrated into CI/CD workflows (e.g., GitHub Actions, Jenkins); the ability to fail builds based on the severity of vulnerabilities found.
🌟 Design space
UI Design
The "UI" for the Ballerina Scan Tool is its output in the developer's terminal during the build process. The design is intentionally minimalist and integrated, presenting security warnings alongside standard compilation errors. The goal is to make security feedback a natural part of the developer's existing workflow.
✍️ CLI Output During bal build
Shell
Compiling source
my_project/main.bal
WARNING [main.bal:(25:12,25:52)] CWE-89: SQL INJECTION
hint: The vulnerability is detected at the 'query' method call. The query is constructed using a template expression that contains a vulnerable expression.
...
WARNING [main.bal:(42:8,42:25)] CWE-798: USE OF HARDCODED CREDENTIALS
hint: Hardcoded credential "admin123" is detected. Avoid hardcoding credentials. Use environment variables or a secret vault.
Run 'bal build' with the '--cloud=docker' option to build the Docker image.
This design provides the file, line number, vulnerability type (mapped to CWE), and a helpful hint for remediation directly in the build log.
Development Phase
Technology Stack Selection
Core Engine - Java (as part of the Ballerina Compiler)
Why Java? The Ballerina compiler itself is implemented in Java. Building the scan tool directly within the existing compiler infrastructure allows it to leverage the same Abstract Syntax Tree (AST) and semantic models. This ensures maximum accuracy, high performance (as the code is only parsed once), and perfect synchronization with the language's evolution.
High-Level Architecture
The Ballerina Scan Tool is not a separate application but a compiler phase.
[Diagram: A flowchart of the Ballerina compilation process. It shows stages like "Lexing & Parsing -> AST Generation" -> "Semantic Analysis" -> "Code Generation". A new box labeled "Security Analysis (Scan Tool)" is inserted after "Semantic Analysis", showing that it operates on the fully analyzed and type-checked AST before code is generated.]
Key Features of the Software
Deep Compiler Integration
Description: Unlike external linters or scanners that re-parse source code, the Ballerina Scan Tool operates directly on the compiler's internal representation (the AST and semantic model). This gives it a complete and accurate understanding of the code, including types, dependencies, and control flow, which allows it to detect complex vulnerabilities with a very low false-positive rate.
Comprehensive Vulnerability Detection
CI/CD Pipeline Integration
Description: Since the scan tool runs as part of the standard bal build command, integrating it into a CI/CD pipeline is trivial. A pipeline that already builds the Ballerina project will automatically run the security scan. The build can be configured to fail if any security warnings are detected, thus acting as an automated security gate.
Challenges Faced and Solutions
Problem: High Rate of False Positives
Early static analysis tools are often plagued by false positives (flagging safe code as vulnerable), which leads to developer frustration and causes them to ignore the tool's output altogether.
Solution: Leveraging the Semantic Model
By integrating directly with the compiler, the tool does more than just pattern-match on source text. It uses the compiler's semantic model to perform data-flow analysis. This means it can trace the flow of data from potentially insecure sources (like an HTTP request) to sensitive operations (like a database query). This contextual understanding allows it to differentiate between a hardcoded string and a dangerous user-provided input, drastically reducing false positives and making its warnings highly reliable.
Future Vision / next steps
Long-term vision
To expand the tool's capabilities beyond security to encompass a full suite of code quality, performance, and reliability checks, making the Ballerina compiler the central hub for ensuring code excellence.
What's next?
Custom Rule Sets: Allow users and organizations to define their own custom security and style rules in a configuration file.
IDE Quick-Fixes: Enhance the Ballerina VS Code extension to provide one-click suggestions to automatically fix the vulnerabilities detected by the scan tool.
SARIF Report Generation: Add an option to export scan results in the SARIF format for richer integration with platforms like GitHub Advanced Security and other third-party dashboards.
Get visibility from recruiters & peers