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.

• 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 [email protected] 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. If you would like to run on our provided demo program instead of your own app, follow the Demo instructions here.

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:

   $ 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:

   $ 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 https://falcon.requiresecurity.com. 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.

   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 [email protected]

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/ and https://aarno-labs.com/

For bug reports, please open github issues or email [email protected]