Gramine is a lightweight guest OS that is designed to run a single Linux application with minimal host requirements. Gramine can run applications in an isolated environment with benefits comparable to running a complete OS in a virtual machine, including guest customization, ease of porting to different host OSes, and process migration.
Gramine supports running Linux applications using the Intel SGX (Software Guard Extensions) technology. Gramine is able to run unmodified applications inside SGX enclaves, without the toll of manually porting the application to the SGX environment. Applications running inside the Gramine SGX enclave become protected against a malicious host. For more information, refer to the Introduction to SGX article.
This page provides an overview of this documentation. Each section is outlined below with a brief explanation and links to specific sub-sections. This page mimics the table of contents in the left-side menu.
Gramine deployment options¶
There are two deployment options for Gramine: protect your container and protect your application. Each option has a dedicated section in the menu, and an introduction is provided below.
Protect your container¶
In this section, we describe how you can protect your Docker container using Gramine Shielded Containers (GSC) and how you can use ready-made SGX images for popular open source projects.
Gramine Shielded Containers
Docker images are used to run applications in the cloud. The Gramine Shielded Containers (GSC) tool transforms a base Docker image into a graminized Docker image that includes the Gramine Library OS and the Gramine-specific app configuration. It enables you to run an application in a Docker container and keep it protected against a malicious host. See the Gramine Shielded Containers article for more information.
Ready-made SGX images
Users can create ready-made SGX Docker images with the help of the “Confidential Compute for X” project. This project provides an interactive script to transform base Docker images to Gramine-protected Docker images. See the Ready-made SGX images article for more information.
Protect your application¶
Use this option to protect an existing application against a malicious host with Gramine. Little to no additional modification of your application is usually needed.
The following steps can be performed to protect your application with Gramine:
- Install Gramine - Install official Gramine packages from the repository of your Linux distribution.
- Run a sample application - Run a sample application to ensure your environment is configured correctly.
You can also check Gramine tutorials.
As a simplified way of protecting your application against malicious hosts you can use Scaffolding for Gramine (SCAG). It is a tool which transforms your application into a graminized Docker image, encapsulating both your application and the Gramine Library OS. It offers seamless support for a variety of frameworks, including but not limited to Flask and Express.js. For a more in-depth exploration, see Scaffolding for Gramine.
To run an application with Gramine, the host platform must be correctly set up first. Further, to achieve security and performance guarantees, Gramine must be configured appropriately for each application.
- Set up the host environment - Set up the host environment and prepare a signing key.
- Provide an application-specific configuration file - Gramine requires a so-called manifest file for each application.
- Set up attestation – If you intend to use remote attestation, you should set up attestation infrastructure.
- Tune performance of application - You may want to tune the performance of your application under Gramine.
This section describes how to develop Gramine. It contains instructions on how to build and install Gramine from source, install dependencies, set up debugging and other processes necessary for Gramine development.
- Build Gramine from source files - Build Gramine and ensure all the dependencies are installed.
- Set up debugging - Run Gramine with GDB.
- Learn about packaging - Package and distribute Gramine on different Linux distributions.
- Use Python API - Use Python API provided by Gramine.
- Writing plugins for signing SGX enclaves - Write plugins for SGX signing tool (gramine-sgx-sign).
We also provide manual pages for Gramine tools.
Contribute to Gramine¶
We encourage anyone who is interested to contribute to Gramine. The below articles contain helpful material for prospective contributors:
- Contributing to Gramine - The Contributing to Gramine page outlines the procedures for performing pull requests, reviews, and regression tests.
- Onboarding - This page describes the knowledge needed to efficiently contribute high-quality PRs to the Gramine project. This page also describes typical flows that Gramine developers should follow to make the process of PR review consistent for everyone involved.
- Development setup - Learn the Emacs and Vim configurations used for Gramine.
- Coding style guidelines - This document describes coding conventions and formatting styles we use in Gramine. All newly committed code must conform to them to pass a review.
- How to write documentation - This section describes how the Gramine documentation is constructed and provides directions on how to contribute to it.
- Developer Certificate of Origin - Affirm that the source code you will submit was originated by you and/or that you have permission to submit it to the Gramine project.
The Gramine project provides resources to help you understand and develop it. The resources page contains a description of features of Gramine, a list of maintainers, a list of users of Gramine, introduction to the Intel SGX technology and a glossary to help you with any questions you may have.
- Gramine features – This page has a comprehensive description of implemented and unimplemented features of Gramine, including the lists of available system calls and pseudo-files.
- Management Team (Maintainers) - This page lists maintainers of Gramine.
- Users of Gramine - See what companies use Gramine for their confidential computing needs.
- Introduction to SGX - Learn about the Intel SGX technology and software stack.
- Glossary - Become familiar with the terms used in Gramine.
For bug reports and feature requests, post an issue on our GitHub repository.