Cheat sheet: 10 Bitbucket security best practices

In this cheat sheet we’ll cover how you can be more secure as a Bitbucket user or contributor. Some of it is specific to Bitbucket, but a lot of it is also useful for other Git and non-Git repositories as well.

Download cheat sheet

So let’s get started with our list of 10 Bitbucket security best practices, starting with the classic mistake of people adding their passwords into their Bitbucket repositories!

1. Never store credentials as code/config in Bitbucket

There are a bunch of great tools available, like git-secrets, that can statically analyze your commits, via a pre-commit Git Hook to ensure you're not trying to push any passwords or sensitive information into your Bitbucket repository. Commits are rejected if the tool matches any of the configured regular expression patterns that indicate that sensitive information has been stored improperly. This may slow down pushes a tiny bit, but it’s well worth it.

Having team-wide rules that prevent credentials from being stored as code is a great way to police bad actions in the existing developer workflow. Use a tool like Vault to help manage your secrets when in production. Lastly, consider using an identity and user management tool chain, like Keycloak (currently maintained by a number of developers in Red Hat) as well as others.

Atlassian supports injecting credentials into Bitbucket plans through environment variables, however a more secure approach may be using Adaptavist’s ScriptRunner as middleware to connect credential and authentication management systems like Vault and Keycloak.

There are many ways to avoid putting credentials into your repository in the first place, and you should try to implement as many as you can; however there’s always the chance some sensitive information may sneak in. You should also consider regularly auditing your repos, making use of tools like GitRob or truffleHog, both of which scan through your codebase, searching for sensitive information via pattern matching.

2. Remove sensitive data in your files and Bitbucket history

If you find sensitive data in your Bitbucket repository, you need to do a number of things to recover. First of all you'll need to invalidate the tokens and passwords that were once public. Once a secret is public on the internet, you should assume it's in the hands of attackers and react accordingly.

Of course, you’ll also need to remove the same sensitive data from your repository, but don’t forget that Bitbucket is very good at keeping a full history of all your commits. This includes changelogs that list your sensitive information. It’s important you clear your Bitbucket history when you remove sensitive data from a repo. For more info, see purging files from your repository's history. Note, while this is a GitHub link, it’s good generic advice for all Git repositories, so you can use it in Bitbucket also. You can also use ScriptRunner to make these integrations simple.

3. Tightly control access

Here in the UK, when it gets really, really hot (read: mildly warm) us Brits tend to open all the windows in the house to make sure that it doesn’t turn into a sauna. However when we leave our houses, we double lock the front door, often leaving many of the windows partially open to keep the airflow moving. Of course this makes no sense, as anyone wanting to break in won’t try to break in through the front door! They’ll look for a less obvious way in, perhaps by climbing through one of the conveniently opened windows. We often take a similar approach to securing our applications. We focus very hard on the more complex attack vectors, but fail miserably against some of the simplest. For instance, it only takes one developer to leave their password on a sticky note, hanging off their monitor for an attacker to gain access. We must ensure our basic settings and practices are adhered to, both on the Bitbucket platform as well as in general. Mandate the following basic practices for your contributors:

1. Require 2-factor-authentication on every contributor’s Bitbucket account.

2. Never let Bitbucket users share accounts/passwords.

3. Any laptops/devices with access to your source code must be properly secured.

4. Repository administrators should manage team access to data. Only give contributors access to the data they need to do their work.

5. Bitbucket accounts may be personal accounts, and do not naturally disappear when users leave the company. Make sure you diligently revoke access from Bitbucket users who are no longer working with you.

Bitbucket’s Branch Permissions model enable you to control who can push commits to which branches.

You can schedule a ScriptRunner job to deactivate particular Bitbucket users at a specified date and time, preventing further access to Bitbucket Server. In the example below we deactivate User and Contractor on 17th August 2018 at 9am. In the Notes section a JIRA issue key ACCESS-1234 has been referenced to see who reported the change.

4. Add a SECURITY.md file

It’s natural for most project owners and maintainers to add a README.md for their repository. In fact, these days it’s expected and it’s quite frowned upon if one is missing. Likewise, it’s becoming increasingly common to add a SECURITY.md file that highlights security-related information for your project. Not only does it give users of your open source project the important security information they need, but it also forces the maintainers to think about how they should deal with security disclosures, updates and general security practices.

Here’s a high level overview of some of the suggested topics that you should cover in the SECURITY.md file:

Disclosure policy

The 2017 Snyk State of Open Source Security report shows only 21% of maintainers who do not have a public disclosure policy have been notified privately about a vulnerability. This jumps up to 73% of maintainers who do have a public disclosure policy. This illustrates the importance of defining the procedure of how an issue reporter can fully disclose security issues responsibly. This should include who to contact and how. This is extremely important as it allows you to gain important feedback from the users of your project. If there's no easy well-defined way of doing something, it's easy for us to not bother doing it at all. Others may log the existence of a vulnerability as an open issue, inadvertently making the world aware of it before a fix is available. Make sure you give your project users all the direction they need to give the right information to project maintainers when issues are found.

Security update policy

Software vulnerabilities are discovered every single day. When a vulnerability is found in your application or library, you have a responsibility to tell the users of your project. They could be using your open source code in production on critical systems. You need to have a well-defined process to share the relevant information to them, including the severity of the vulnerability, the risk it brings, and how to move to a fixed version of your code. Define this process upfront so that the information is pushed to your project users, allowing them to be updated as early as possible about new security vulnerabilities as they are found and fixed. This might be as simple as a security mailing list. A SECURITY.md file is a good home for such info on the repo, and if you have a website, consider an independent page for it — see Express.js’s security page as an example.

Security related configuration

The security considerations of your project go beyond your code alone. Users of your open source project likely need to add configuration to your project and create settings in order for it to work as necessary in their environment. You should provide your project users with suggested settings that harden their security posture when deploying this project. Examples include turning on HTTPS, adding an authorization layer and of course replacing default passwords (guidance many MongoDB users wish they’ve gotten). Remember that many users typically have a fairly low understanding of security, so any advice you can pass on will help them greatly.

Known security gaps & future enhancements

There’s a tradeoff between giving your users the information they need to secure their environment versus enabling an attacker with suggested attack routes. Always consider how the information you share could be used by both parties. Very rarely are projects in such a state that all the security improvements you want to make have been implemented. It's important to inform your project users of the security controls that aren’t currently in place. Your users deserve to know the full story so they can make informed decisions about how they use your project. Who knows — you may even get contributions of a security control implementation from your users on the list!

5. Get security tips as part of your workflow with Code Insights

Code Insights is designed to surface information relevant to a pull request, so the author and reviewers are able to make better-informed decisions. Snyk provides an integration that runs a scan against all opened pull requests to ensure they aren’t introducing new open source vulnerabilities, and can block pull requests from being merged when they do contain new vulnerabilities.

If a new vulnerability is found, Snyk alerts you about the newly found vulnerability and opens a Fix pull request, including suggested upgrades or Snyk patches to fix the vulnerability.

In Bitbucket’s pull request interface, the changes are scanned and results are shown as detailed in-line annotations next to the changes that introduce new issues. These annotations make it easier to understand the results of Snyk’s scan and support informed decisions.

For more information about installation and usage, check this Snyk Bitbucket Code Insights blog post containing a video of it all happening!

6. Validate your Bitbucket applications carefully

All good platforms can be extended, and Bitbucket with its application marketplace is no exception. Applications are written by organizations and third party developers, so keep this in mind when adding them to your repository. Consider the following when selecting and installing Bitbucket applications:

• Don’t give applications more access rights than they need.

• Question why an application requires the level of access it asks for, and think about the damage it might cause with that level of access.

• Validate that the author or organization behind the application are legitimate and have credibility before giving them access to your repositories, the same as you would when onboarding a new committer to your project.

You’re only as secure as your weakest link, so if an application you’re giving access to has a poor security posture, a breach of their code gives attackers access to your code - one of your most sensitive assets.

Lastly, make sure you monitor or audit your applications and their contributors at regular intervals to ensure you still need them, still trust them, and still deem them worthy of the access they require. Keep on top of your application management and remove those that you no longer need or require rights that you’re not comfortable giving.

7. Add security testing to PRs

Bitbucket has a powerful event-driven Git Hook framework that allows you to send HTTP POST requests to a service of your choice when events are fired. There are a vast number of events you can choose to act upon, but one of the most useful for testing your incremental code changes is the pull_request event. There are many static code analysis tools that support Git Hooks such that when a PR is created, an HTTP POST is fired to prompt them to test your latest updates. This is a great point in time to ensure that code and config changes being made are aligned with your security expectations.

Snyk, as an example, statically analyzes your repo to find vulnerable dependencies you may be using and helps you fix them. You can test your repos through Snyk’s UI to find issues, but also to keep developers from adding new vulnerable libraries by testing pull requests and failing the test if a new vulnerability was introduced.

Beyond the convenient integration into Bitbucket, pull requests are better than “breaking the build” in the fact that they don’t have to block a merge (in fact, they’re informational by default), and their ability to test your changes, not just the outcome (e.g. fail only if you introduced a vulnerable library, not if there was one there already).

In addition to Snyk, you should also consider using SonarCloud or CodeClimate to perform automated security code reviews. Additionally consider adding a ScriptRunner script to ensure you aren’t pushing any secrets into your repo.

8. Add security testing in your Bitbucket pipes

Bitbucket Pipes allows you to customize and automate a CI/CD workflow from a group of ready-to-use tasks. Snyk provides a ready-to-use pipe that scans your application dependencies and Docker images for known open source security vulnerabilities as part of the continuous integration/continuous delivery (CI/CD) workflow.

To add the Snyk pipe to your workflow, simply copy the Snyk pipe and paste it into the pipeline.

Once added to the Bitbucket Pipeline workflow, the Snyk pipe scans your dependencies for open source vulnerabilities as part of the CI/CD workflow. If vulnerabilities are found, the Snyk pipe gates the process according to your pre-configured setup. For example, preventing high severity vulnerabilities from going through the build. For more information, please check the documentation pages.

Another pipe that you should consider including in your pipeline to improve your security resilience is SonarCloud.

9. Use the right Bitbucket offering for your security needs

Depending on your project or organizational regulations, you may be restricted to software that can only run locally. Or perhaps the restrictions are placed on where your source code is stored or on which other organizations can have access to it. This is a common restriction for financial institutions, government departments or other tightly regulated industries. However this doesn’t mean that you can’t use Bitbucket!

Take a look at the fully on-prem Bitbucket Server offering, which allows you to fully host Bitbucket repositories within your organization. This means your can be disconnected from the internet and still have internal access to your projects within your Bitbucket Server repositories.

10. Rotate SSH keys and personal access tokens

Bitbucket access is typically done using SSH keys or personal user tokens (in lieu of a password, because you enabled 2FA!). But what happens if those tokens are stolen and you didn’t know? Be sure to refresh your keys and tokens periodically, mitigating any damage caused by keys that leaked out.

For further reading on Bitbucket security, make sure you also read the Bitbucket security advisories. And if you haven’t done so yet, make sure you download this cheat sheet now and pin it up, so your future decisions are secure decisions!