Inside TREsPASS.js: A Research-Grade JavaScript Library for Modeling Socio-Physical Security Threats

Hook

Most security libraries focus on purely digital threats, but what happens when you need to model an attack that combines social engineering, physical intrusion, and cyber exploitation in a single coherent framework?

Context

The TREsPASS (Threat REsearch Platform for Socio-Physical Attack Security Studies) project emerged from a recognition that modern security threats rarely exist in isolation. A sophisticated attack on a financial institution might begin with an employee being tailgated into a restricted area, proceed to a USB drop in the parking lot, and culminate in privilege escalation across the network. Traditional threat modeling tools treat these as separate domains—physical security over here, cybersecurity over there, human factors somewhere else entirely.

Funded by the European Union's Seventh Framework Programme, TREsPASS aimed to create a unified framework for modeling these complex, multi-domain attack scenarios. The trespass.js library represents the JavaScript implementation of this vision: a modular toolkit for representing security models, generating attack trees, and performing analysis across socio-physical attack surfaces. While the project has concluded and the library shows minimal community adoption (sitting at just 4 stars on GitHub), it offers a fascinating glimpse into academic approaches to security modeling and the challenges of building domain-specific security tooling.

Technical Insight

The architecture of trespass.js reflects its academic origins through a clean separation of concerns across five core modules. The model module provides data structures for representing security scenarios, the attacktree module handles attack tree generation and manipulation, the analysis module implements security analysis algorithms, the api module creates an interface layer for external services, and utils provides shared functionality. This modular design allows consuming applications to cherry-pick only the functionality they need.

The library's approach to attack tree generation is particularly interesting. Rather than requiring manual construction of attack trees (a notoriously tedious process), trespass.js can generate them programmatically from high-level security models. Here's a simplified example of how the library might be used to define a security model and generate an attack tree:

const trespass = require('trespass');

// Define a security model with locations, actors, and assets
const model = trespass.model.create({
  locations: [
    { id: 'lobby', security: 'low' },
    { id: 'serverRoom', security: 'high' }
  ],
  actors: [
    { id: 'attacker', type: 'external' },
    { id: 'employee', type: 'internal' }
  ],
  assets: [
    { id: 'database', location: 'serverRoom', value: 'critical' }
  ],
  paths: [
    { from: 'lobby', to: 'serverRoom', requires: 'badge' }
  ]
});

// Generate attack tree from the model
const attackTree = trespass.attacktree.generate(model, {
  goal: 'access:database',
  attacker: 'attacker'
});

// Analyze the attack tree for feasibility and cost
const analysis = trespass.analysis.evaluate(attackTree, {
  metrics: ['cost', 'probability', 'detectability']
});

console.log(analysis.optimalPath); // Most likely attack sequence

What makes this approach powerful is the ability to express security policies and physical constraints declaratively, then let the analysis engine discover attack paths you might not have considered. The library can identify multi-step attacks that combine social engineering (convincing an employee to share credentials), physical exploitation (tailgating through secure doors), and technical compromise (accessing the database).

The dual-target design for Node.js and browser environments is implemented through careful avoidance of platform-specific APIs in the core modules, with environment detection for features like file I/O. This allows the same model definitions and analysis code to run in a backend service processing batch threat assessments or in a browser-based interactive modeling tool. The build pipeline uses browserify or webpack to create browser-compatible bundles, making integration relatively straightforward.

One architectural decision worth noting is the library's heavy use of immutable data structures for representing security models and attack trees. This functional approach makes it easier to reason about transformations and analysis steps, though it does introduce a learning curve for developers more accustomed to object-oriented modeling. The attack tree representation uses a nested object structure where each node contains its type (AND/OR gates representing whether all conditions or any single condition must be met), children nodes, and metadata about costs and probabilities.

Gotcha

The most significant limitation of trespass.js is its documentation—or rather, the lack thereof. The repository contains minimal README documentation and no comprehensive API reference. Understanding how to actually use the library requires reading through source code, and the absence of examples means you're essentially reverse-engineering the intended usage patterns. This isn't uncommon for academic research code, but it makes adoption nearly impossible for anyone outside the original research team.

Beyond documentation, the library's tight coupling to the TREsPASS project's specific methodologies and data formats creates integration challenges. The model format appears to be designed around the project's particular research goals rather than general-purpose security modeling. If your threat models don't fit the socio-physical attack paradigm that TREsPASS targeted—for instance, if you're modeling purely cloud-native threats or IoT device vulnerabilities—you'll likely find the abstractions more constraining than helpful. The library also appears to be unmaintained, with no recent commits and no indication of ongoing support. Given that the EU-funded research project has concluded, there's no clear path for bug fixes or feature enhancements. The minimal community adoption (4 stars suggests almost no external usage) means you won't find StackOverflow answers or community plugins to fill the gaps.

Verdict

Use if: You're specifically working within the TREsPASS project ecosystem, need to integrate with existing TREsPASS tools or data formats, or are conducting academic research on socio-physical attack modeling where the library's particular abstractions align with your needs. It could also serve as a reference implementation if you're building your own attack tree generation system and want to study one academic approach. Skip if: You need production-ready security modeling tools with active maintenance and community support, want comprehensive documentation and examples, or are working on threat models outside the socio-physical attack domain. For most developers, well-maintained alternatives like OWASP Threat Dragon or Microsoft's Threat Modeling Tool will provide better value with less friction. The reality is that trespass.js appears to have been built for internal research use rather than broader consumption, and its minimal adoption reflects the challenges of translating academic security research into practical developer tools.