Lesson 1 of 3
Secrets in code
Listen to an AI summary of Secrets in code
What is a secret
A secret is a value that grants access when the value is used, such as a password. Anyone who learns a secret can use the secret.
What is an API key
The sports shop uses a payment provider, a company that takes card payments for websites. The sports shop sends each payment as a request to the API of the payment provider.
An API key is a secret that a program sends to an API to prove which program is asking. The payment provider gave the sports shop the API key payments-key-for-the-shop. Anyone with the API key can send requests as the sports shop, such as a refund to a card.
What is a key
The sports shop encrypts the home address of each customer. Encryption is scrambling data so that only the intended person can read the data. A key is a secret value that locks or unlocks encrypted data.
A secret typed into the code
A hard-coded secret is a secret typed into the source code. The example is a commit to the sports shop.
Each added line starts with a plus sign. The code is Python. Look at the text in quotation marks.
Take payments by card.The second line puts the API key in the variable api_key as a string. The third line sends the API key and the payment to the payment provider.
The code works. The weakness is the place where the API key is kept (use of hard-coded credentials, CWE-798). Credentials are secrets that prove who is asking.
Who can read a hard-coded secret
The code of the sports shop is in a repository, which keeps the history of every change. Everyone who can read the repository can read the API key, on any computer with a copy.
Why deleting the line is not enough
A person on the team notices the API key and deletes the line in a second commit. The newest code no longer has the API key, but the repository keeps every earlier commit.
A removed line starts with a minus sign.
Anyone who opens commit 1 or commit 2 can read the API key.
Rewriting the history to take a secret out is a separate, careful job, and copies made earlier still have the secret.
Hard-coded keys
A key typed into the code is a hard-coded secret too (use of a hard-coded cryptographic key, CWE-321). Cryptographic means used for encryption.
Every club that installs the shop software then has the same key. One leak of the code reveals the key of every club. A safer design makes a new key for each club and keeps the key outside the code.
Handling secrets
Secrets are kept out of the code and out of any configuration file, a file of settings, in the repository. Two places for a secret are an environment variable and a secrets manager, which is the preferred place.
What is an environment variable
An environment variable is a named value that is set outside the code. The software reads the value while the software runs. A person types the API key into the settings of the server, so the API key is not in the repository.
Look at the part after the equals sign.
api_key.In Python, os.environ holds the environment variables. The name in square brackets picks the environment variable named PAYMENT_API_KEY. The code now has the name of the secret and not the secret. When the environment variable is missing, the line stops with an error.
JavaScript, another programming language, reads the same value as process.env.PAYMENT_API_KEY.
What is a secrets manager
A secrets manager is a service that stores secrets and controls who can read each secret. The software asks the secrets manager for a secret when the software runs. A secrets manager records every read, and a team can replace a secret without changing the code.
- Examples of secrets managers
- AWS Secrets Manager, Azure Key Vault, Google Cloud Secret Manager and HashiCorp Vault.
- Examples of hosting platforms
- Vercel, Netlify and Heroku, companies that run websites and set environment variables on a settings page.
After a secret is found
A reviewer who finds a secret asks the team for two things. The first is rotation, replacing the secret with a new secret and switching the old secret off. The second is moving the new secret into an environment variable or a secrets manager.
The sports shop asks the payment provider for a new API key and switches off payments-key-for-the-shop. The API key in commit 1 then grants no access.
Examples of good practice
- Each copy of the software has its own secrets. A key from a test copy cannot reach the data of real customers.
- Each part of the software gets only the secrets that part needs.
- A secret is rotated when someone with access leaves, or when a leak is suspected.
- A secret never appears in a log (a record of events), an error message, a web address or the code sent to the browser.
- A secret scanning tool such as gitleaks searches the repository for secrets (covered in an earlier lesson). A setting named push protection stops a commit with a secret from reaching the shared repository.
Secrets the application stores
The sports shop also stores the credentials of customers, such as a password. A credential with too little protection is a weakness (insufficiently protected credentials, CWE-522), covered in the lessons on storing a password and sending data.
Examples of what to look for
- A string given to a variable named
password,secret,key,tokenorapi_key. - A database address with a user name and a password inside, such as
postgres://shop:[email protected]/shop. - A file that holds a key added to the repository, or a
.envfile, which lists environment variables and their values. - A default for a secret, such as
os.environ.get("SECRET_KEY", "changeme")in Python. The live shop runs with the valuechangemewhen the environment variable is missing. - A secret written to a log or an error message, such as
print(api_key). - A key in a test file or an example file. A key labelled as a test key can be a real key.
- A removed line that has a secret. The secret was in a commit, so the secret needs rotation as well as removal.
The example search is for Python and JavaScript.
The options -rniE search every file in the folder shop, ignore capital letters and print line numbers. The pattern finds password, secret, api_key or token before an equals sign or a colon.
Check your understanding
Name two things a team does after a secret is found in a repository.
Show the answer
The team rotates the secret, and moves the new secret into an environment variable or a secrets manager.
Which line of the diff with the note
Take payments by cardhas a hard-coded secret?Show the answer
The line
api_key = "payments-key-for-the-shop", where the API key is a string typed into the code.Give one reason why deleting the line in a later commit does not protect the secret.
Show the answer
The repository keeps every earlier commit, so anyone who opens the earlier commit can still read the secret.
Practise it
Challenges with a weakness this lesson teaches.
- Gift searchGiftwrap, BeginnerOpen
- Go live checklistSwiftcart, IntermediateOpen
- Open banking importBrightledger, IntermediateOpen
- Password resetGradebook, BeginnerOpen