Design Security with Style (Guides)

Last month, we looked at the value of “shifting left” on security for your API programs. This month, we’re back with some practical ideas about how to make that happen.

Security is something you do, not something you are. While we absolutely embrace the value of shifting your mindset to think of security as a product feature, we also want to be clear that a mindset isn’t enough. Security breaches often exploit tiny details, and hackers are continually evolving their techniques. Your security practices need to be similarly nimble and tactical.

One weapon in your repository can be a security-style guide. Your API teams may already use style guides to automate the enforcement of data formats or endpoint naming conventions. With a well-chosen set of enforceable security rules, you can use the same tools to dramatically fortify your defenses against data theft and resource exploits.

Follow Enduring Security Models

The good news, as we’ve said before, is that you don’t have to do this on your own. The Wild West mentality of Y2K-era hacker movies has been restored by greater professionalism on both sides. Hackers are more sophisticated than ever, but security professionals across the industry are also working together to share intelligence, develop strategies, and coordinate responses. While some aspects of security require secrecy, there is now widespread acceptance that improved security for internet users, in general, is a victory for anyone doing business online.

For API developers and product managers, this means a wealth of information and tools is available to make your security processes more effective. The requirements for apps offered through major app stores and integration providers are one place to look for guidance on what to include in your security style guide—these rules are battle-tested and user-tested, and they reflect some hard-won lessons:

• Android’s Core App Quality guidelines for security and privacy lay out the basic requirements in a clear format that keeps the principles separate from any branded tools.
• Slack’s Authentication Best Practices guide for integrations goes into detail on credential management.
• Square’s General Development Considerations include explanations of best practices for HTTPS, error handling, and information collection. They also have great details on when to use different credentials during the software development lifecycle.
• Salesforce requires a partner account to see the most detailed requirements for their AppExchange, but the company bases specific rules on Secure Coding Guidelines that are publicly available.
• AND–if you’re a Stoplight fan–we now have an OWASP security ruleset style guide template available in Stoplight Platform or in our open-source linting tool, Spectral.

You might notice that all of these companies reference the work of OWASP, the Open Web Application Security Project. OWASP is an industry nonprofit dedicated to improving software security, and it provides virtually all the resources you might need to build a comprehensive API security program. OWASP’s reports and standards are virtually required reading for cybersecurity professionals.

Start with Solid Basics

Just as industry-leading companies do, your organization can follow the OWASP lead with confidence. OWASP resources, which include Dependency-Track for monitoring third-party libraries and the Web Security Testing Guide, are comprehensive, with attention to every level of web development. As you progress in your security program, guidance from OWASP can provide you with some reassurance that you’re on the right track.

OWASP’s best-known resource is its annual Top Ten report on the state of web security. OWASP’s top 10 is a regularly-updated report outlining security concerns for web application security, focusing on the 10 most critical risks. The report is mainly intended to raise awareness, and it is more descriptive than prescriptive. (For teams looking for a specific compliance standard to enforce at the product level, the Application Security Verification Standard is the appropriate OWASP tool.)

What we can do with the Top Ten is use it to discuss which aspects of application security can be addressed in a style guide and which will need to be addressed in other ways. The next section goes through the current Top Ten report and splits out a few details from each category to show what principles you might include in your security style guide.

Get Style Inspo from the OWASP Top Ten

While many organizations use the Top Ten as a set of standards, OWASP makes it clear that it is just a starting point for developing a more comprehensive approach. We’re taking that same approach—below is a partial list of what might go in your API security style guide. It would need to be turned into specific enforceable policies before you could use it in any automated governance tooling. It’s still a great place to start – it just isn’t the end. Let’s dig in!

1. Broken Access Control

Access control failures are authorization failures—users are somehow acting “outside of their intended permissions.” Companies that deal with sensitive data need to pay special attention to these vulnerabilities to ensure the “principle of least privilege” is maintained, but any API that separates user roles requires authentication, limits Cross-origin resource sharing, or separates public and private resources are at risk. Style guides can address these risks:

• Disable CORS by default, and enable it only as needed for specific endpoints and origins.
• Verify user permissions and record ownership with each HTTP request.
• Rate limit endpoint access and use error handling to disable rapid retries.

2. Cryptographic Failures

Contrasting data types require different levels of protection, including distinguishing between data in transit and data at rest. When encryption is required, protocols must be followed exactly, and deprecated encryption methods need to be replaced. Your style guide can check these encryption standards:

• Require the use of HTTPS for all API traffic.
• Encrypt all sensitive data at rest, and do not retain any more data than absolutely necessary.
• Disable caching on any responses where sensitive data might be transmitted.
• Verify that any encryption is using a current, appropriate algorithm and randomization method.

3. Injection

Any application that makes use of SQL, NoSQL, OS commands, ORMs, LDAPs, Expression Languages, or graph navigation libraries is vulnerable to injection attacks. APIs are particularly vulnerable to injection attacks because user-supplied data is often a crucial part of the product. Any time you accept PUT requests without thorough data validation, filtering, sanitization, or context-aware escaping, you run the risk of taking in malicious data. You can help prevent injection attacks with these additions to your security style guide:

• Disallow user-supplied structure names.
• Avoid accepting dynamic queries. Prefer queries with fixed parameters wherever possible.
• Make use of the SQL command `LIMIT` and do not accept queries including `EXECUTE IMMEDIATE` or `exec()`.
• Prefer the use of ORMs over direct commands.

4. Insecure Design

OWASP highlights the need to do security planning before actual application coding begins, with attention to threat modeling, design patterns, and data segregation—a call for the design-first approach we always suggest for APIs. OWASP’s most important step for preventing insecure design is in-depth risk profiling and threat modeling so that you deeply understand the unique vulnerabilities of your API program. Because this category of threat is mostly focused on the earliest phases of the software development lifecycle, you likely won’t address it directly in your style guide.

5. Security Misconfiguration

Throughout your application stack, each server, framework, and database must be set up with appropriate security features enabled. Regardless of your specific server configuration, cloud provider, or authentication library, adding the following items to your style guide can help reduce your risk:

• Require temporary ports to be closed automatically after use.
• Remove permissions for default passwords and credentials.
• Require error handling to avoid revealing stack traces or other configuration details.
• Replace or remove deprecated endpoints and duplicate or unnecessary functionality.

6. Vulnerable and Outdated Components

The log4j vulnerability discovered in November 2021 had existed since at least 2013 and affected software made by virtually every major tech company. That bug got a lot of attention, so most development teams deployed a fix quickly. That’s not the norm, though, and a stunning number of serious security breaches target software that could have been patched. You will need to develop an ongoing, sustainable plan for monitoring and updating dependencies, but your API style guide can help with enforcement:

• Require removal of unused dependencies, components, and files.
• Maintain a list of deprecated dependencies and force upgrades or removal on all code.
• Prefer signed packages and verified local installations.
• For dependencies from remote repositories, only allow secure connections to a known source

7. Identification and Authentication Failures

Proper authentication and authorization processes, consistently applied, are a critical part of your API security. Once you have determined the appropriate processes for your APIs, enforce them strictly using your style guide:

• If multi-factor auth is required, do not allow authentication without it.
• Prevent the use of simple `Authorization` headers.
• Use password quality checks and enforce evidence-based password policies.
• Use standardized error handling for all types of auth failure to obscure the cause of the failure.
• Require logging of all failed login attempts.
• Do not allow session IDs in URLs or server caches. Automate token handling and session disposal.

8. Software and Data Integrity Failures

Excessive automation of your dependency upgrades can also introduce risk. You’ll need to find a way to keep versions current without exposing yourself to the risk of “impostor” upgrades. Reducing external dependencies is one strategy, but not a complete solution. Many widely used tools include some kind of digital signature that you can (and should) validate, but many dependencies won’t have this.

One approach is to host your own internal dependency server, allowing only carefully vetted libraries, and then requiring your API teams to use only these tools. Another option is to use a tool like OWASP’s Dependency-Check in your CI/CD pipeline. In an ideal world, you’d decide how you’ll manage this risk before your development teams begin writing code—once they’ve begun integrating external tools, it becomes much harder to implement any of these policies. As a result, this isn’t really a threat you can address with your API style guide beyond the rules outlined in category six.

9. Security Logging and Monitoring Failures

You may already be logging metadata from your APIs for performance insights or traffic analysis. Metadata is also a valuable security tool, but simply creating logs doesn’t bring you any greater security. Inconsistent or inappropriate logging can actually introduce more risk. You can create rules in your style guide to enforce the specific formats required by your logging tools and to manage what data is logged appropriately to your API:

• Enforce data formats as required by your log management system.
• Log user behavior in a consistent, traceable, but anonymized format.
• Prevent logging of personally identifiable information and sensitive data.
• Create additional controls and audit details for metadata related to high-value transactions.
• Protect access to your logs by keeping them with a secure data provider or on a private server.
• Implement alerts for suspicious patterns in metadata as they are logged.

`10. Server-Side Request Forgery

SSRF attacks exploit the fact that many public-facing APIs are essentially middleware between the client and a network of private backend servers. If the servers are not properly secured, an attacker can cause the public API server to make a GET request to an unintended private location. These attacks typically use some variation on `localhost` or `127.0.0.1`, an IP address reserved for network loopbacks. Authentication functions on those endpoints won’t be triggered, because the request is coming from a machine inside the same trusted network.

Many of the most effective prevention strategies for SSRF attacks have already been covered, but there are a few more details you can include in your API style guide:

• Limit GET requests from the public server to URLs on a whitelist (or positive allow list).
• Disable HTTP redirects (response codes 300-399). Handle routing errors with client error codes (400-499) and UI elements for manual redirects.
• Prevent raw data responses to the client and even potentially to the internal public server.

And that brings us to the end of the Top Ten. It may feel like you’ll never be able to do it all—after all, OWASP’s “quick reference” is 17 pages long! But breaking concepts down into smaller pieces is the only way to make progress, and in security, every improvement matters.

Putting security measures in your API style guides is a big step in the right direction. Automating compliance is the next step, and it doesn’t have to be daunting.

Share Your Style with Sound Processes and Tools

API developers benefit from style guides when they are well-organized, shared in a convenient format, and enforced with as much automation as possible. Earlier this year, we spent some time looking at API style guides, including how they’ve evolved, how to evaluate your need for a style guide, and resources to help you create the best style guide for your needs. A few principles stood out:

• Timely information delivered concisely is easier to act on than long-form explanations.
• Developers want access to navigable, organized, in-depth explanations on demand.
• Clear policies around the most crucial details increase confidence.
• Automated tools for linting & compliance make developers’ lives easier & improve code quality.
• Changes to guidelines need to be disseminated quickly, and a clear “single source of truth” should be established.
• Collaboration is welcome—there’s no reason to go it alone and many reasons to embrace standards.

The same principles apply when we focus on the security components of your API style guide. Determining the specific details of your policies is an important step, but we all know that publishing a list of rules is no guarantee that those rules will be followed. To get value from the work you put into your security style guide, you’ll need to make it available to developers in discrete, purposeful chunks and build in enforcement mechanisms.

Stoplight provides tools to help you make that happen: Spectral has made API-style compliance nearly as simple as standard code linting, and it works well for security rules. If you are supporting multiple APIs, you may also want to use Stoplight’s Style Guide Projects to improve governance across your programs. Many of the OWASP top issues relate to inconsistency, and Stoplight’s goal is to help you deliver your best, most secure API products as consistently as possible.

If you’re feeling the Hacktoberfest spirit, consider contributing to our open-source OWASP Ruleset for Spectral on Github! Stoplight teams are always working to model the best practices we promote, and together, we can create a powerful tool to improve security across the web.