npm package: @reqsec/falcon-nodejs-instr
Description: Falcon NodeJS instrumentation
Author: Aarno Labs / Require Security
Latest version: 0.9.1

<a href="" title="Falcon">
    <img src="docs/img/Falcon-logo-and-text.png">
</a>

[![npm version](https://badge.fury.io/js/@reqsec%2Ffalcon-nodejs-instr.svg)](https://badge.fury.io/js/@reqsec%2Ffalcon-nodejs-instr)
[![Static Badge](https://img.shields.io/badge/dashboard-link-blue)](https://falcon.requiresecurity.com)
[![Static Badge](https://img.shields.io/badge/dashboard-self_host-green)](https://falcon.requiresecurity.com/falcon-dashboard.zip)


**Falcon is a security tool that can block application-level attacks in JavaScript**. Falcon provides fine-grained insight and control on how application modules access sensitive information. This protects against users from threats that often originate in third-party and open source libraries.

Key features of Falcon:

- **JavaScript Application Protection**: Alert or completely block most code injection or path traversal vulnerabilities.
- **Privilege Protection**: Automatically learn privileges used by an application. Using these privileges, block any application requests that violate privilege controls.

- **Application Insight**: unique instrumentation provides detailed information on libraries used in the application, whether they are directly or indirectly loaded at runtime, and the associated privileges of individual application libraries.

<a href="docs/img/dashboard-preview.png">
<img align="right" width="400" src="docs/img/dashboard-preview-dark-small-round.png"/>
</a>

- **Context Sensitivity**: Unlike the experimental nodejs permissions model, Falcon allows privileges on a per-library or per-file basis. This allows the application to perform sensitive tasks with one module while protecting against vulnerabilities in others

- **Real-Time Monitoring**: Falcon comes with a dashboard which updates with application insights in real-time, including libraries used, privileges thereof, and any violations of the existing privilege model.

**PLEASE NOTE**: This is an early version of Falcon. If you try it and run into issues, please email at contact@requiresecurity.com or open a github issue. Currently only fs, http, https, net, and child_process APIs are fully covered

## Getting Started
Follow the below instructions to quickly set up Falcon to run on your application. For additional configuration and installation instructions, see our [full installation instructions](docs/install.md). If you would like to run on our provided demo program instead of your own app, follow the [`Demo` instructions here](docs/tutorial.md).

Falcon works with node v16.20+, or node v20.8+ if you want to instrument an application that uses ES6 modules

1. **Install**:

   To install the latest Falcon release, go to the root of the project you would like to instrument, and npm install:

    ```bash
    $ npm install @reqsec/falcon-nodejs-instr
     ```

2. **Setup**:

   Set Falcon as a node options preload. Note that after this point, every node process launched from the instrumented terminal will be instrumented:

    ```bash
    $ export NODE_OPTIONS="--require @reqsec/falcon-nodejs-instr"
     ```
3. **Run Your Application**:

    Restart or launch your application in the instrumented terminal. The instrumentation will not take effect until you have restarted the application

4. **Load Dashboard**:

   Load the dashboard by going to <a href="https://falcon.requiresecurity.com">https://falcon.requiresecurity.com</a>. By default, falcon will connect to port `4000`.

   If you would rather self-host or want to run Falcon with different settings, follow the [full installation instructions](docs/install.md).

   Click `connect` in the dashboard landing page.

## Explore
**Learning**

  The top left status box should now show app status as `connected` and mode as `learning`.

  Even without any input to your application, you should see libraries show up on the dashboard. Any library which your application loads will show up in the `Libraries` tab when it's loaded, and in the `Privileges` tab, you will be able to see the privileges used by said library as those privileges are exercised.

  As your application receives inputs and does new things, new privileges (and new libraries, depending on your architecture) will show up on the dashboard.

  Once you are satisfied with the displayed libraries and privileges, you can move to the `Controls` tab.

  The `Export` button will export a trace of all instrumentation events the dashboard has received. It can be reloaded from the dashboard splash screen.

**Alerting**

`Enable Alerting` will move Falcon from learning to alerting mode. Once in
alerting mode, you cannot move back to learning mode (without restarting the
app), and unlike learning mode, alerting mode will not add new privileges.
Instead, if alerting mode sees a privilege that violates policy, it will raise
an alert, which will show up in the Alerts tab.

If you want to approve an alert and add it to your app's privileges, you can click the `Learn` button under `Failure Reason`.

From alerting mode, you can move back and forth between alerting and block
modes. In block mode, whenever an attempted privilege violation is detected, the
instrumentation will throw an error (thus preventing the violation) as well as logging a message.

If you see spurious events (or don't see fs, child_process, or network events that you expected to see), please file a bug on github or email contact@requiresecurity.com

# Contact
Falcon was pioneered at Aarno Labs in partnership with leading government research organizations, and has since transitioned to release under Require Security.

Require Security is a cyber security focused spinout of Aarno Labs, LLC.

Aarno Labs is a leading cyber security R&D company that specializes in solving extremely difficult computer security challenges by developing advanced automated techniques.

Visit us at [https://www.requiresecurity.com/](https://www.requiresecurity.com/) and [https://aarno-labs.com/](https://aarno-labs.com/)

For bug reports, please open github issues or email contact@requiresecurity.com