Introduction

You are reading the security handbook of the Stacks ecosystem.

Target audience: everyone

The world out there is scary and adversarial. Regardless of what you do at Stacks, you MUST read this handbook and apply its best practices to keep you (and the ecosystem) safe. Where appropriate, you will also find more specific pointers (e.g., if you are a developer, a trader, etc.).

How to use this handbook

Security always involves trade-offs (e.g., against usability). We need our ecosystem to be safe, but we also need to get work done. This handbook tries to make all this as easy as possible for you, by:

Clearly calling out what is non-negotiable from a security standpoint (MUSTs).
Making it as easy as possible for you, the reader, to follow what is required...
...while ensuring you understand why requirements are there and what threat model they protect from.

In practice, this means that this handbook will tell both the requirements and how to implement them, so you do not need to reinvent the wheel or venture on a number of side-quests.

Where possible, a secure setup should be the default (e.g., when using a pre-configured laptop).

You SHOULD NOT deviate from what is recommended unless you have an excellent reason to do that. If you think that's the case, check with your line manager.

Must read

Threat Model

Security is never absolute, instead always relative to a set of threats. This page describes the threat model for this handbook.

A remote attacker going for monies 💰

99% of the time, attackers will go after crypto (tokens, stablecoins, you name it). 99% of those times, the attack will play by the following book:

Spear phishing: Email, Telegram messages, fake meeting invitations. Anything to get you to download and execute a malicious file/application (technically, a "payload").
Local device compromise: The malicious file/applications gives an attacker (full) control of your machine. They will leverage it to grab any secret you have access to and to spread further (e.g., to other members of your organization).
Grab and run: The attacker will enumerate all secrets on your system (usernames, passwords, seeds to wallets, cryptographic keys, etc.) and steal them. Then (sometimes a few weeks after) they will use those secrets to steal crypto funds and/or impersonate you, so they can spread the attack further.
Lateral movements: Impersonating you (e.g., on Telegram) allows the attacker to reach out to your social network (e.g., BD partners, fellow developers, etc.) and spear phishing them. So the cycle begins again.

This handbook will mostly focus on the threat model we just described, since they account for 99% of the crypto heist we have collectively seen so far as an industry.

In a few cases, the threat model will also expand to include additional threats (e.g., evil maids). When that happens, you will find it properly highlighted.

The remaining 1%

It is easy to think about additional threats, e.g. sophisticated attackers that have deep pockets and are willing to spend millions of dollars to circumvent the defenses we (as an ecosystem and as an industry) put up.

Those threats do exist, but they are order of magnitudes less frequent than all the others. An attacker will not spend a few million dollars 0-day to remotely compromise you if they can just get you to click on a link and install their malware.

For these reasons, this handbook will focus on the 99% threats that are prevalent, while giving advanced readers pointers on how to (try to) mitigate the remaining 1%.

If you believe you are being targeted by an attacker outside the threat model depicted above, reach out!

At a high level

The attacker we are modeling for will only manage to steal secrets they can access from your machine. They can't steal what is not there or can't be reached from it.

The majority of the requirements and recommendations in this handbook will diligently work in that direction: By ensuring your machine holds as few secrets as possible (ideally none!). Then, multi-factor authentication through external wallet keys will do the rest.

What does this mean in practice?

No cryptographic keys

You MUST NOT, under any circumstances, store cryptographic keys or wallet seeds where an attacker can read them from your machine. You MUST NOT store them in a password manager, as files, images, etc. Instead, use hardware wallets.

Why?: An attacker compromising your device will not be able to steal cryptographic keys from it if they are not there.

2FA: Always and on hardware devices

You MUST enable two-factor authentication on any and all your accounts. The second factor MUST be a hardware device (e.g., your smartphone, or a security key).

Your organization will implement Single sign-on on as many services as possible. This way, you will only need to handle one account (e.g., for Google Workspace).

Why?: An attacker who compromised your device might be able to get your passwords, but they won't be sufficient without second factor (which will NOT be on your device, but on separate hardware).

Separate devices for work

You MUST use a separate device exclusively for work.

Why?: So that an attacker cannot compromise your personal accounts if they manage to compromise your work device.

Hardware security keys

Hardware security keys allow you to securely keep second factors and cryptographic keys physically separated from your work device (e.g., your laptop). In addition, these keys will not unlock their secrets unless you touch them, proving you are physically present.

All this ensures that a remote attacker who controls your machine cannot use your security key. We will use hardware security keys for multi-factor authentication.

Which key should you get?

We recommend getting at least two Yubikey 5C, providing connectivity through USB-C (so you can plug it into your laptop and most phones) and NFC.

You MUST keep one of them on you at all times and leave the other in a safe place (so that if you lose one, you have a backup).

We will be using these keys for:

WebAuthn (everyone, used for passkeys)
OATH - TOTP (everyone, used for TOTPs)
FIDO2 (if you are a developer, used for SSH)
SmartCard / PIV (if you are a developer, used for SSH when FIDO2 is not an option)

Configuration

To configure your Yubikey(s), install the Yubico Authenticator. In case you need them, here are its full docs.

Disable Yubico OTP

We will not be using Yubico OTP, so you can disable it (if the authenticator proposes it after you have plugged in the Yubikey).

Set a FIDO PIN

You MUST set a FIDO PIN on your Yubikey(s). This ensures that if it gets lost or stolen, an attacker cannot use it without also knowing the PIN.

Go to the app Configuration, then navigate to "FIDO/Manage PIN". Follow the instructions to set a 4-digits PIN.

If you are on iOS, you will need to use NFC instead of USB-C. Put your Yubikey on a table, touch it with the top of your iPhone. It will prompt you to open the authenticator.

Set an OATH password

You MUST set a OATH password so that, similarly as we did for the FIDO PIN, a lost Yubikey can't be used without it.

Read here for instructions.

When asked by the application, you can protect your password with FaceID (or similar) to improve UX.

Using your hardware security key

Continue to use your hardware security key for:

Multi-factor authentication

Multi-factor authentication ensures that if your username/passwords are ever compromised, an attacker will not be able to authenticate as you, missing something else – typically, "something you have".

Here are the "multiple factors" we will be using:

Username
Password: "something you know"
Hardware security key: "something you have"

You MUST enable multi-factor authentication for all your accounts on all services. For this to be effective, you MUST keep factors separate from each other. This means that you MUST NOT store your second factor in your password manager. Instead, use hardware security keys.

Which second factor

Passkeys

The modern and most secure way to add a second factor to your account is through passkeys. They provide good UX and are resistant to phishing.

If a service allows you to use passkeys as a second factor, you MUST prefer it to any other method. Setting things up depend on each service, for instance:

When authenticating to a service, you will be asked for a username and password, then prompted to insert your security key, insert its FIDO PIN, and then touch it to confirm your presence.

Some services will also allow "passwordless" login, where the security key is enough to authenticate.

Time-based one-time password

If a service does not support passkeys (yet), they will use TOTPs as an alternative.

Please see here for how to setup TOTPs for your Yubikeys.

When authenticating to a service, you will be asked for your TOTP for that account. Use the Yubico Authenticator to get it (instructions here).

What about recovery codes?

When setting up multi-factor authentication, some services will prompt you to store some recovery codes to use in case you lose your hardware security key. While it might be tempting to go on and store them in your password manager, you MUST NOT do that, as it would defeat the purpose of the second factor.

Instead, either:

register multiple hardware second factors (so that you cannot lock yourself out) and destroy the recovery codes;
print out the recovery codes as store them in a safe.

What about my phone number?

SMS-based two-factor authentication is insecure and MUST NOT be used; instead, rely on hardware devices. SIMs can be unfortunately swapped. When that happens, the attacker will control second factor.

If you need to use a service that will only allow phone number 2FA, reach out!

Cryptographic wallets

A wallet holds a set of private keys (very large, random numbers) that can be used to spend coins. All these keys are generated from a seed phrase. The seed phrase is the key to the kingdom! You MUST NEVER store the seed phrase anywhere accessible via a device (be it a file, a digital note, a picture, or even an entry in a password manager). Similarly, you MUST NEVER share it with another user.

Ground rules

You MUST NEVER store seed phrases digitally
You MUST NEVER share seed phrases with other users
You MUST NEVER use wallet browser extensions

Warm wallets: <$1K

If you are storing less than $1K, you MAY use a software wallet on your smartphone since it is more convenient to use than a hardware wallet. You MUST NOT use a browser extension on your laptop, because it is easier for an attacker to compromise it. You SHOULD hand-write the seed phrase generated by the mobile wallet and store it in a safe place. You MUST NOT store it digitally.

Cold wallets: <$1M

If you are storing up to $1M, you MUST use a hardware wallet, such as a Ledger device. These keep the private key encrypted inside the device, and are resistent to tampering. Teams MUST have a set of N >= 3 devices, with transaction outputs spendable by any of the devices (1 of N multisig), so hardware failures do not result in losing funds. For N < 5, at least one team member MUST keep a backup device or seed phrase in a safe deposit box. For N >= 5, the risk of leaking the backup device or seed phrase is greater than the risk all devices failing, so backups MUST NOT be made.

If you need to store more than $1M, you MUST contact us for specific instructions.

Clear signing

You MUST ALWAYS verify, to the extent possible, the destination address(es) of any transaction you send. Many recent attacks, from ByBit to the latest NPM poisonings, have surreptitiously replaced user specified data with attacker data, resulting in stolen funds. In some cases the true data displayed after alteration, in others not.

To combat this, Ledger devices support clear signing. This uses the hardware screen of a Ledger device to display a human readable description of the transaction before you agree to sign. While the frontend app that interacts with your Ledger device may more easily be compromised, the hardware screen is much more resistent to such attacks.

When you verify an output address such as a smart contract (SC), you MUST verify the address from an external source, such as previously downloaded documentation. SC calls though involve not just addresses, but also functions and parameters; verify that the entire SC call is what you have intended. User wallet addresses MUST also be verified; when possible, this should include a voice call with the user in question where the address is read and the voice is recognized.

So for software wallets, you MUST ALWAYS confirm the details before agreeing to sign. This will NOT stop all attacks, which is why you SHOULD ALWAYS consider using hardware wallets even when not required to do so. For hardware wallets, you MUST ALWAYS confirm the details on the hardware screen.