npm package: @nesgaurd/nesgaurd-js
Description: Protect your website from malicious script modifications and supply chain attacks with NESGuard SRI monitoring
Author: NESGuard Security
Latest version: 1.0.0

# NESGuard JavaScript SRI Protection

A JavaScript client for adding Subresource Integrity (SRI) protection to your web applications, providing real-time script tampering detection and enhanced security against supply chain attacks.

[![Test Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen.svg)](https://github.com/nesgaurd/nesgaurd-js)
[![npm version](https://img.shields.io/npm/v/@nesgaurd/nesgaurd-js.svg)](https://www.npmjs.com/package/@nesgaurd/nesgaurd-js)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)

## What is NESGuard?

NESGuard is a comprehensive Subresource Integrity (SRI) monitoring platform that protects your website from malicious script modifications, supply chain attacks, and third-party script compromises. This package is the JavaScript client that integrates with the NESGuard monitoring service.

### How It Works

1. You integrate this client into your website
2. The client monitors scripts for integrity changes
3. When changes are detected, you're alerted in real-time
4. The NESGuard desktop agent provides detailed forensic information

## Complete Setup Guide

### Step 1: Create a NESGuard Account

Before using this package, you need to:

1. Visit [nesgaurd.com](https://nesgaurd.com) to create an account
2. Generate an Agency ID from your dashboard
3. Download and install the NESGuard Desktop Agent for your operating system (available for Windows, macOS, and Linux)
4. Configure the desktop agent with your Agency ID and API credentials

### Step 2: Install the JavaScript Package

```bash
npm install @nesgaurd/nesgaurd-js
```

Or include via CDN:

```html
<script src="https://cdn.jsdelivr.net/npm/@nesgaurd/nesgaurd-js/dist/nesgaurd.min.js"></script>
```

### Step 3: Set Up Your Website Integration

```javascript
import NESGuard from '@nesgaurd/nesgaurd-js';

// Initialize NESGuard client
const nesguard = new NESGuard({
  agencyId: 'your-agency-id', // Get this from your NESGuard dashboard
  apiUrl: 'https://nesgaurd.com/api' // Optional, defaults to production API
});

// Setup script monitoring
nesguard.setup();
```

### Step 4: Configure the Desktop Agent

1. Open the NESGuard Desktop Agent
2. Enter your Agency ID and API credentials
3. Configure monitoring preferences and alert thresholds
4. Set up notification channels (email, SMS, webhook)

## Security Features

NESGuard JS includes advanced security measures:

- Real-time script integrity monitoring
- Automatic SRI attribute management
- Instant alerts for script modifications
- Protection against supply chain attacks
- Code obfuscation to protect against reverse engineering
- Domain locking to prevent unauthorized usage
- Self-defending code to prevent tampering
- Debug protection to hinder analysis attempts
- 100% test coverage for reliability

## Dashboard and Monitoring

The NESGuard platform provides:

- Real-time monitoring dashboard
- Detailed script integrity history
- Threat intelligence and analytics
- Forensic information for compromise investigation
- Team collaboration features
- API for custom integrations

Visit [nesgaurd.com/dashboard](https://nesgaurd.com/dashboard) after setting up your account to access these features.

## Configuration Options

When initializing NESGuard, you can provide several configuration options:

```javascript
const nesguard = new NESGuard({
  agencyId: 'your-agency-id',          // Required: Your unique agency identifier
  apiUrl: 'https://nesgaurd.com/api',  // Optional: API endpoint for NESGuard service
  scripts: [                           // Optional: Additional scripts to monitor
    'https://example.com/script.js',
    '/local/script.js'
  ],
  autoDetect: true,                    // Optional: Auto-detect scripts on page (default: true)
  interval: 900000,                    // Optional: Monitoring interval in ms (default: 15min)
  onDetection: (event) => {            // Optional: Callback when integrity violation detected
    console.error('Script integrity violation:', event);
  }
});
```

## Methods

### `setup()`

Sets up SRI protection by scanning the page for scripts and registering them with the NESGuard service.

```javascript
nesguard.setup();
```

### `addScript(url, options)`

Manually add a script to monitor.

```javascript
nesguard.addScript('https://example.com/script.js', {
  interval: 60000, // Check every minute
  critical: true   // Mark as critical script
});
```

### `removeScript(url)`

Stop monitoring a specific script.

```javascript
nesguard.removeScript('https://example.com/script.js');
```

### `checkScript(url)`

Force an immediate integrity check of a script.

```javascript
nesguard.checkScript('https://example.com/script.js')
  .then(result => {
    console.log('Script integrity status:', result.isValid);
  });
```

## Setup Wizard

NESGuard includes a setup wizard to help you configure which scripts to monitor:

```javascript
import { NESGuardWizard } from '@nesgaurd/nesgaurd-js';

// Launch the setup wizard
NESGuardWizard.launch({
  agencyId: 'your-agency-id',
  onComplete: (config) => {
    // Save configuration and initialize NESGuard
    localStorage.setItem('nesguard-config', JSON.stringify(config));
    const nesguard = new NESGuard(config);
    nesguard.setup();
  }
});
```

## CDN Usage

When using the CDN version, the code is already built, bundled, and obfuscated:

```html
<!-- Include the script -->
<script src="https://cdn.jsdelivr.net/npm/@nesgaurd/nesgaurd-js/dist/nesgaurd.min.js"></script>

<!-- Use it in your code -->
<script>
  document.addEventListener('DOMContentLoaded', () => {
    // Initialize NESGuard
    const nesguard = new NESGuard({
      agencyId: 'your-agency-id'
    });
    
    // Setup protection
    nesguard.setup()
      .then(() => {
        console.log('NESGuard protection active');
      });
  });
</script>
```

## CMS Integrations

### Drupal Integration

```javascript
// In your Drupal theme's JavaScript
import NESGuard from '@nesgaurd/nesgaurd-js';

document.addEventListener('DOMContentLoaded', () => {
  const agencyId = drupalSettings.nesguard?.agencyId;
  
  if (agencyId) {
    const nesguard = new NESGuard({ 
      agencyId,
      apiUrl: drupalSettings.nesguard?.apiUrl || 'https://nesgaurd.com/api'
    });
    nesguard.setup();
  }
});
```

### WordPress Integration

```javascript
// In your WordPress theme or plugin
document.addEventListener('DOMContentLoaded', () => {
  if (typeof nesguardSettings !== 'undefined') {
    const nesguard = new NESGuard({ 
      agencyId: nesguardSettings.agencyId,
      apiUrl: nesguardSettings.apiUrl || 'https://nesgaurd.com/api'
    });
    nesguard.setup();
  }
});
```

## Advanced: WebSocket Monitoring

For real-time notifications:

```javascript
import { NESGuardSocket } from '@nesgaurd/nesgaurd-js';

const socket = new NESGuardSocket({
  agencyId: 'your-agency-id',
  token: 'your-jwt-token' // Get this from your authentication system
});

socket.connect();

socket.on('threat', (data) => {
  console.error('Threat detected:', data);
});
```

## License

MIT