LunaSec is a suite of security tools designed to protect sensitive data in web applications by only adding a few lines of code.
- What is LunaSec?
- Documentation
- System Architecture
- Who is LunaSec for?
- How does LunaSec work?
- Custom Support from the LunaSec Team
- Trying LunaSec in 1 minute
- Deploying LunaSec
- Need Help?
- Contributing
- See Also
LunaSec is an end-to-end security system designed to protect your application by transparently encrypting sensitive data. It works seamlessly by storing your sensitive data and then giving you back a Token (a UUID) to retrieve data with later. Tokens aren't sensitive values by themselves, thereby limiting the impact of security issues in your application when exposed, and also provide the foundation that LunaSec builds on to offer you additional security and compliance features.
- Secure By Default: Prevents data leaks by making your software resistant to many security issues like SQL Injection, XSS, and even RCE.
- Best-In-Class Compliance Software: Decrease your compliance overhead by 90%+ with centralized access control logic, audit logs, and automatic compliance validation.
- Simple Onboarding: Get started in minutes by adding only a few lines of code anywhere that sensitive data enters or exits your system.
- Built By Security Experts: Designed to bring leading security practices to your applications without requiring advanced security knowledge.
- Self-Hosted And Open: You retain control over your data by hosting LunaSec yourself. It's open source software licensed under a permissive Apache2.0 license.
- Trustless Architecture: All records are encrypted with a unique key that even LunaSec can't access. Decryption only happens when you need it to.
- Scales Automatically: Supports even the largest loads by leveraging cloud-scale database services like AWS S3 and DynamoDB.
- Enterprise Grade: We offer warranties, managed deployments, and custom support via our Premium Support packages.
You can read more here about what features LunaSec provides.
For more information about LunaSec including tutorials, examples, and technical information, please review our documentation. For technical questions or help, please reach out via our GitHub Discussions board or open a new GitHub issue if you have a bug or feature to request.
Please visit our website for marketing or sales information, or to get in contact.
LunaSec works across the components of your web stack to provide end-to-end data security. We've documented the components of the stack here and in the diagram below.
LunaSec is designed to be used by anybody that needs to store sensitive information in a production web application. Despite being built by Security Engineers, LunaSec does not require security expertise to get started. It's designed to be used by ordinary Software Engineers and Developers.
Reasons to use LunaSec:
- Security & Data Privacy Compliance: GDPR defines sensitive data include Name, Email, Phone Number, IP Address, Credit Cards, and more. If you are subject to data privacy regulations and store any of that data, then LunaSec will help you achieve compliance more easily.
- Data Leak Protection: If you store data that needs to remain securely stored and private, then LunaSec will greatly increase your defenses against unauthorized data leaks.
- Data Inventory: The centralized nature of LunaSec makes it easy to track and monitor what data you're storing, who and when it's used, and help you enforce access controls around that data.
The LunaSec stack spans from the front-end to the back-end of your application and works alongside your existing code to keep your data encrypted and secure. To get started, please check out the steps below ("Trying LunaSec in 1 minute").
LunaSec is similar to a safety deposit box that holds your sensitive data. Each piece of data gets a unique box, a unique key to unlock it, and a unique number to identify each box by. These boxes are then securely stored inside a bank vault that only a banker with special permissions has access to. Accessing the box requires proof of ownership and the key to unlock the box.
The boxes that the data is stored in are unable to be opened without the key. That means that even if the bank is evil, they can't open the box. Even if the box is stolen by a thief, the thief can't open the box without the keys. Only you are able to open the box.
Even if a thief steals the keys, they still have to get access the box either through the banker or by breaking into the bank. One is useless without the other.
That's the core value that LunaSec provides for you. LunaSec runs the bank, hires the bankers, and keeps your boxes secure. You just have to provide the data and keep track of the keys to access it.
We've designed LunaSec to mitigate many common security vulnerabilities that developers face. Each component of the LunaSec stack is designed to provide protection against specific attack scenarios. Please read more about the security of LunaSec here.
We offer paid support, onboarding, and additional enterprise features for LunaSec to help you reach your security or compliance milestones faster. Our team of security engineers is very flexible and happy to work with you.
If you're interested, please send us a message.
We've made it very easy for you to get familiar with LunaSec by running our example app locally.
You can try it out with one command if you have Node and Docker installed:
npx @lunasec/cli start --env demo
That will pull all the Docker containers and start the LunaSec demo app on your computer. It's a simple web app that you can play with in your browser.
Once it's running, just sign up for a new account and then submit some fake data in the app. (It's a fake account that's on your computer only)
All data in the app is transparently encrypted and stored in the LunaSec database in the app. Take a look at the elements on the page and the network requests to view how it's all working.
For a deeper dive into the Demo App, please see this page for a walkthrough of everything. All the source code is available here for you to view.
If you run into any issues, please open up a GitHub issue or chat with us on our GitHub Discussions page.
In order to use LunaSec in your production environment, you will need to host a copy yourself. We have made available a deployment CLI tool to make this task easier. Currently, only AWS is support. You don't need to use AWS for your application to use LunaSec, however. You just need to have an AWS account for LunaSec to deploy to. (LunaSec will work with any app running anywhere)
To get started deploying LunaSec, please see our docs here.
If you find yourself stuck, you're missing a feature, or you just want to clear up some confusion, then please head over to our GitHub Discussions board to talk with our team.
We're a small team and our resources are limited for how much assistance we've able to provide. If your needs are urgent, or you would like us to review your code/implementation, then please consider inquiring about our custom support packages.
We welcome community contributions, and we've documented the requirements for contributions here.
For more information about LunaSec including tutorials, examples, and technical information, please visit our documentation. For marketing information, sales, or to get in touch, visit our website: https://www.lunasec.io/.
The rest of this ReadMe explains how to work on LunaSec itself. If you simply want to use LunaSec, please see the documentation.
This repo contains all public LunaSec code: the LunaSec SDKs, backend services, demo applications, documentation, and supporting scripts.
We have split code first by language, and then by purpose.
Our backend services and CLI tools are all written in Golang and live in /go
.
Our web components and NPM modules are all written in TypeScript and live in /js/sdks/packages
.
Our Demo Apps are also written in typescript and live in /js/demo-apps/packages
.
Docs live in docs
, and the OpenAPI Spec for our internal REST API lives in api-spec
.
Path: /js/demo-apps/packages
Demo apps that use our toolkit for testing and demonstration. The react-app and node-app are the one's currently being developed. These are our only SDK supported frameworks currently.
Path: /js/sdks/packages
Contains front and backend SDKs.
They're all written in Typescript and outputs to a few different formats:
- ES5 build (polyfills ES2016 modules)
- ESNext build (uses ES2016 modules)
- Browser build (concatenated into one file that's loaded into browser global namespace)
Path: /js/sdks/packages/secure-frame-iframe
This holds the SDK frontend components which load into the iframe. The React SDK uses this to isolate sensitive data from front-end apps by using the iframe as an isolated "sandbox". We've hardened this iFrame by adding a very strict Content Security Policy (CSP) that limits the impact of any security issues by heavily restricting network access.
Path: /go
These are the back-end components of the LunaSec stack. They share a common codebase and are built into separate binaries
by the entrypoints defined in the /go/cmd
folder, the most important being the tokenizerbackend
.
You can build each entrypoint by using the Makefile like: make tokenizerbackend
and then invoking the generated binary
inside of the build
folder like: ./build/tokenizerbackend_dev
.
Please read our contributor instructions before forking and submitting a pull request. It's short and it's very helpful if you're going to be working on LunaSec.
To launch and use LunaSec to help you develop your application, see the documentation. To work on LunaSec itself, follow these steps:
Install all dependencies by running lerna bootstrap
and be patient.
Configure the LunaSec CLI tool to be used locally by running yarn run lunasec:setup
. The lunasec
command will not be accessible on your path.
Then, install tmuxp
and run tmuxp load ./start-with-tmuxp.yaml
in the root directory.
You can inspect that file to see what commands are all being run if you'd like to start the cluster without tmuxp.
Note: You'll have to provide your password for the ./go/scripts/start-tokenizerbackend-dependencies.sh
command to start.
Open your browser and navigate to http://localhost:3000
to see the demo application.
When you want to shut down the cluster, hit ctrl+b
and type :kill-session
. (It's just tmux)
A CLI has been written in go to enable the creation of test data. Build the cli via:
cd go
make tokenizer tag=cli
and use it by running
./build/tokenizer_cli COMMAND
We use Lerna to manage the monorepo, and we use yarn as the package manager.
Because yarn doesn't know about local packages like Lerna, we can't use yarn add
to install dependencies.
To add a dependency to a package, either edit it manually into the package.json
and run lerna bootstrap
,
or use lerna add <dependencyname> <path/to/package/youre/working/on>
.
Our Tokenizer API is defined by the OpenAPI standard (previously named Swagger) and can be found in the folder /api-spec
in the project root.
If the spec changes, the generated code that relies on the spec will need to be regenerated.
For example, in the tokenizer-sdk package, run yarn openapi:generate
to regenerate the API client.
A similar pattern can be used (check the package.json) to generate an api client in any language you wish,
by simply specifying the OpenAPI generator name when calling the openapi-generator
NPM package .
Our goal is to build a sustainable business to support LunaSec and finding the right balance to enable us to build a community while also enabling our business is our primary motivation. If you have thoughts on how we can improve our approach, we would love to hear from you.
Please send us an email at developer-feedback at lunasec dot io or file an issue on this repository.
The release process will be handled automatically by our CI/CD system.
Under the hood, the release process is split up into four parts:
- Version bump
- Compile artifacts
- Publish artifacts
- Push version tag to repository
Breaking this process up ensures that every part completes without error before moving onto the next step. This greatly reduces the event that some artifacts get published and others do not, leading to a headache of a time debugging a release.
Deployment of the releases is done by Github Actions.
Versioning for releases is done by lerna.
Since the monorepo has both go and node code, compilation happens in multiple places. For the node sdks, every package has their own compilation package.json script which gets run. The entrypoint which calls into each package’s script is here. For the go code, all compilation code exists within the Makefile under the release target.
For node artifacts, everything is handled by lerna. For go, publishing is handled by the publish target of the Makefile. Artifacts end up in NPM, DockerHub, and Github.
The version tag that gets pushed contains the version changes for the bumped monorepo version. Here is an example commit.