Attestium

📄 Read the Technical Whitepaper — 16 pages covering our architecture, security model, TPM 2.0 integration, and adoption roadmap.

Element of Attestation - Runtime code verification and integrity monitoring for Node.js applications

Attestium is a project by Forward Email – the 100% open-source, privacy-focused email service.

We created Attestium to provide transparent, hardware-backed proof of our own server-side code integrity. We believe in open, verifiable systems, and Attestium is our contribution to a more trustworthy internet.

🧪 What is Attestium?

Attestium is a runtime code verification and integrity monitoring library that provides cryptographic proof of your application's code integrity. Like an element in the periodic table, Attestium represents the fundamental building block of attestation - the ability to prove that your code is running exactly as intended, without tampering or modification.

Core Concept: Element of Attestation

Just as chemical elements have unique properties and atomic structures, Attestium provides:

• Symbol: At (for Attestation)
• Atomic Properties: Stable verification states, tamper-reactive bonds
• Chemical Reactions: Cryptographic verification processes
• Molecular Structure: File checksums linked by cryptographic bonds

🎯 Why Attestium Exists

The Problem: Trust in Distributed Systems

In today's world of cloud computing and distributed systems, users need to trust that:

• The code running on servers matches what's published in repositories
• No unauthorized modifications have been made to running applications
• Third parties can independently verify system integrity
• Changes to code are immediately detectable

Research Background

Attestium was developed based on extensive research into existing solutions and their limitations. This research was inspired by:

• Forward Email Technical Whitepaper - Requirements for transparent, auditable email infrastructure
• Mullvad System Transparency - Approaches to system transparency and verification

[!NOTE] Research Foundation: Attestium addresses the specific need for runtime code verification that emerged from Forward Email's commitment to transparency and Mullvad's pioneering work in system transparency.

🔍 Comprehensive Analysis of Existing Solutions

Before developing Attestium, we conducted extensive research into existing verification, attestation, and integrity monitoring solutions. This comprehensive analysis examines 20+ solutions across different categories to understand their capabilities, limitations, and suitability for runtime code verification.

Why Existing Solutions Weren't Sufficient

Based on our comprehensive analysis, we identified critical gaps that existing solutions couldn't address for our specific requirements:

1. Runtime Application Verification Gap

• Problem: Most solutions focus on build-time, deployment-time, or infrastructure-level verification
• Impact: Cannot detect runtime tampering or code injection attacks
• Attestium Solution: Continuous runtime monitoring with real-time verification

2. Third-Party Verification API Gap

• Problem: Existing solutions lack standardized APIs for external verification
• Impact: Difficult for auditors to independently verify system integrity
• Attestium Solution: RESTful APIs with nonce-based challenge-response protocols

3. Developer Experience Gap

• Problem: Hardware-based solutions require specialized knowledge and infrastructure
• Impact: High barrier to adoption for typical web applications
• Attestium Solution: Simple npm package with software fallback for development

4. Node.js Ecosystem Gap

• Problem: Most solutions are language-agnostic or focused on other platforms
• Impact: Poor integration with Node.js applications and workflows
• Attestium Solution: Native Node.js integration with runtime hooks

5. Cost and Complexity Gap

• Problem: Enterprise solutions are expensive; hardware solutions are complex
• Impact: Unsuitable for many applications and organizations
• Attestium Solution: Free, open-source, software-only implementation

6. Granular Monitoring Gap

• Problem: File integrity tools monitor files; application tools monitor performance
• Impact: No solution provides granular application code verification
• Attestium Solution: File categorization with application-aware monitoring

7. Continuous Verification Gap

• Problem: Most solutions provide point-in-time verification
• Impact: Cannot detect tampering between verification intervals
• Attestium Solution: Continuous background verification with configurable intervals

🧪 Attestium's Unique Approach

Attestium addresses these gaps by providing:

✅ Runtime Code Verification

• Continuous monitoring of running application code
• Real-time detection of unauthorized modifications
• In-memory integrity checking capabilities

✅ Third-Party Verification APIs

• RESTful APIs for external verification
• Nonce-based challenge-response protocols
• Cryptographically signed verification reports

✅ Developer-Friendly Design

• Simple npm package installation
• Minimal configuration requirements
• Integration with existing Node.js applications

✅ Granular File Categorization

• Intelligent categorization of source code, tests, configuration, and dependencies
• Customizable include/exclude patterns
• Git integration for baseline establishment

✅ Cryptographic Proof Generation

• SHA-256 checksums for all monitored files
• Signed verification reports
• Tamper-evident audit trails

✅ Modern Workflow Integration

• Git commit hash tracking
• CI/CD pipeline integration
• Cosmiconfig-based configuration management

🔒 Tamper-Proofing and Security Considerations

The Challenge of Runtime Tampering

One of the most significant challenges in software verification is preventing runtime tampering - the ability for malicious actors to modify code in memory after it has been loaded and verified. Traditional approaches like Object.freeze() and VM isolation provide some protection, but determined attackers with system access can potentially bypass these mechanisms.

Attestium's Multi-Layered Defense

Attestium employs several innovative approaches to address runtime tampering:

1. Tamper-Resistant Memory Protection

• VM-Based Isolation: Critical verification logic runs in isolated VM contexts
• Proxy Protection: Function interception prevents runtime modification of verification methods
• Original Function Capture: Core JavaScript functions are captured before they can be overridden

2. External Validation Network

• GitHub Release Verification: Compares local code against signed GitHub releases
• Multi-Source Validation: Cross-references multiple trusted external sources
• Distributed Challenge System: External services provide unpredictable validation challenges

3. Continuous Integrity Monitoring

• Real-Time Checksums: Continuous validation of file and memory integrity
• Behavioral Analysis: Monitors for suspicious modification patterns
• Audit Trail: Tamper-evident logging of all verification activities
• Audit Status Integration: Enterprise-grade continuous monitoring with automated server auditing, webhook notifications, and TPM-backed verification

Limitations and Considerations

While Attestium provides significant protection against tampering, it's important to understand the fundamental limitations of software-only solutions:

The Verification Paradox

• Core Challenge: How do you prove integrity when an attacker controls the verification system?
• Mitigation: External validation and distributed verification reduce single points of failure
• Reality: Perfect tamper-proofing may require hardware-based solutions (TPM, HSM, etc.)

Practical Security Model

Attestium is designed to:

• ✅ Detect casual tampering and unauthorized modifications
• ✅ Raise the bar significantly for sophisticated attacks
• ✅ Provide audit trails for forensic analysis
• ✅ Enable external verification by independent parties
• ⚠️ Cannot prevent determined attackers with root access and unlimited time

Best Practices for Maximum Security

1. Deploy in Controlled Environments: Use containers, restricted user accounts, and access controls
2. Enable External Monitoring: Set up independent verification nodes
3. Regular Baseline Updates: Keep verification baselines current with legitimate changes
4. Combine with Other Security Measures: Use alongside firewalls, intrusion detection, and access logging
5. Monitor Verification APIs: Watch for unusual patterns in verification requests

🔐 TPM 2.0 Hardware-Backed Security

Why TPM 2.0 is Critical for Attestium

Attestium requires TPM 2.0 for production deployments where maximum security is needed. While Attestium can operate in software-only mode for development and testing, TPM 2.0 integration is essential for addressing the fundamental limitations of software-only verification systems.

[!IMPORTANT] TPM 2.0 Requirement: For production environments handling sensitive data or requiring regulatory compliance, Attestium must be deployed with TPM 2.0 hardware support. Software-only mode should only be used for development, testing, or non-critical applications.

The Fundamental Problem: Software-Only Verification Limits

Attack Vectors Possible Without TPM 2.0

When running in software-only mode, Attestium is vulnerable to several sophisticated attack vectors:

• Runtime Patching: An attacker with root access can modify the Node.js runtime or kernel to bypass Attestium's checks.
• Memory Manipulation: Direct memory access can alter verification logic or cryptographic keys.
• Filesystem Tampering: An attacker can modify files on disk and then intercept filesystem calls to return the original content to Attestium.
• Verification Bypass: The entire verification process can be mocked or disabled by a sufficiently privileged attacker.

How TPM 2.0 Solves These Problems

TPM 2.0 provides a hardware root of trust that mitigates these attacks:

• Hardware-Protected Keys: Cryptographic keys are stored in the TPM chip and cannot be extracted.
• Measured Boot: The TPM measures the entire boot process, creating a cryptographic record of the system state.
• Sealed Storage: Data can be encrypted and "sealed" to a specific system state. It can only be unsealed if the system is in the exact same state.
• Remote Attestation: The TPM can provide a signed quote of its internal state, allowing a remote party to verify the system's integrity.

TPM 2.0 Architecture in Attestium

block-beta
  columns 2
  block:app["Attestium Application"]:2
    columns 2
    block:sw["Software Verification"]
      A["File checksums"]
      B["Runtime monitoring"]
      C["External validation"]
      D["Tamper detection"]
    end
    block:hw["TPM 2.0 Hardware Integration"]
      E["Hardware random generation"]
      F["Cryptographic attestation"]
      G["Sealed storage"]
      H["PCR measurements"]
    end
  end
  block:tpm["TPM 2.0 Hardware Chip"]:2
    columns 2
    block:left[" "]
      I["Secure key storage"]
      J["Hardware RNG"]
      K["Sealed data"]
    end
    block:right[" "]
      L["Platform measurements"]
      M["Attestation signing"]
      N["Tamper resistance"]
    end
  end

Attestium's TPM 2.0 Integration

Attestium leverages these TPM 2.0 features to provide a secure verification environment:

• Key Management: Attestium's cryptographic keys are generated and stored in the TPM.
• Integrity Verification: The TPM is used to verify the integrity of the boot process and the running system.
• Sealed Data: Verification baselines are sealed to the TPM, preventing tampering.
• Hardware Random: The TPM's hardware random number generator is used for cryptographic operations.

🚀 Quick Start

1. Installation

npm install attestium
# or
pnpm add attestium

2. Basic Usage

const Attestium = require("attestium");

async function main() {
  const attestium = new Attestium({
    projectPath: process.cwd(),
    autoDetectTpm: true,
  });

  const report = await attestium.generateVerificationReport();
  console.log("Verification Report:", report);

  const securityStatus = await attestium.getSecurityStatus();
  console.log("Security Status:", securityStatus);
}

main().catch(console.error);

⚙️ Configuration

Attestium uses cosmiconfig for configuration. You can configure Attestium in:

• package.json (attestium property)
• .attestiumrc.json
• .attestiumrc.yml
• attestium.config.js

Configuration Options

🤖 Continuous Monitoring with Audit Status

For enterprise-grade continuous monitoring, automated server auditing, and real-time notifications, use Audit Status, which is built on top of Attestium.

Upptime Integration

You can integrate Audit Status with Upptime for a comprehensive uptime and integrity monitoring solution.

1. Expose an audit health endpoint on your server. See the health endpoint example.
2. Add the endpoint to your .upptimerc.yml:

sites:
  - name: Production API
    url: https://api.example.com

  - name: Production Audit Status
    url: https://api.example.com/health/audit
    expectedStatusCodes:
      - 200

🤝 Contributing

Contributions are welcome! Please see our contributing guidelines for more information.

📜 License

Attestium is licensed under the MIT License.