cyshield-sdk/README.md

Firewall SDK to protect web apps by validating IP addresses and providing real-time threat monitoring.

# CyShield SDK

A React SDK for integrating CyShield's web application firewall protection into your applications. Simply wrap your app with our protection components and get enterprise-grade security.

## 🛡️ Protection Features

- **Real-time IP Validation** - Automatic blocking of malicious IP addresses
- **Threat Detection** - AI-powered threat identification and prevention
- **Behavioral Analysis** - Monitor and block suspicious user behavior
- **Traffic Logging** - All security events logged to your dashboard
- **Zero Configuration** - Works out of the box with minimal setup
- **Enterprise-grade Security** - Powered by CyShield's threat intelligence

## 📦 Installation

```bash
npm install cyshield-sdk
```

or

```bash
yarn add cyshield-sdk
```

## 🚀 Quick Start

### Basic Protection

```jsx
import React, { useEffect } from "react";
import { ProtectedPage, setConfig } from "cyshield-sdk";

// Import credentials from environment variables
const API_KEY = import.meta.env.VITE_APP_FIREWALL_API_KEY;
const APP_ID = import.meta.env.VITE_APP_FIREWALL_APP_ID;

function App() {
  useEffect(() => {
    setConfig({
      API_KEY,
      APP_ID,
      DEBUG: true,
    });
  }, []);

  return (
    <ProtectedPage>
      <YourAppContent />
    </ProtectedPage>
  );
}

export default App;
```

### Enhanced Protection

```jsx
import React, { useEffect } from "react";
import { EnhancedProtectedPage, setConfig } from "cyshield-sdk";

const API_KEY = import.meta.env.VITE_APP_FIREWALL_API_KEY;
const APP_ID = import.meta.env.VITE_APP_FIREWALL_APP_ID;

function App() {
  useEffect(() => {
    setConfig({
      API_KEY,
      APP_ID,
      REALTIME_MONITORING: true,
      DEBUG: true,
    });
  }, []);

  return (
    <EnhancedProtectedPage
      enableBehaviorTracking={true}
      enableIPAnalysis={true}
      onThreatDetected={(threat) => {
        console.log("Threat detected:", threat);
        // Handle threat detection (e.g., show alert)
      }}
    >
      <YourAppContent />
    </EnhancedProtectedPage>
  );
}

export default App;
```

## 🎛️ Configuration

### Environment Variables Setup

Before using the SDK, set up your environment variables:

```bash
# .env file
VITE_APP_FIREWALL_API_KEY=your-api-key-here
VITE_APP_FIREWALL_APP_ID=your-app-id-here
```

### SDK Configuration Options

```javascript
import { setConfig } from "cyshield-sdk";

setConfig({
  // Required
  API_KEY: "your-api-key",
  APP_ID: "your-app-id",

  // Optional
  REALTIME_MONITORING: true,
  DEBUG: false,
  LOG_LEVEL: "info", // 'debug', 'info', 'warn', 'error'
});
```

## 🔧 API Reference

### Functions

#### `setConfig(config)`

Configure the SDK with your credentials and settings.

```jsx
import { setConfig } from "cyshield-sdk";

setConfig({
  API_KEY: "your-api-key",
  APP_ID: "your-app-id",
  REALTIME_MONITORING: true,
  DEBUG: true,
});
```

**Parameters:**

- `config: object` - Configuration object with API_KEY, APP_ID, and optional settings

### Components

#### `<ProtectedPage>`

Wraps your application with basic firewall protection.

```jsx
import { ProtectedPage } from "cyshield-sdk";

<ProtectedPage>
  <YourApp />
</ProtectedPage>;
```

**Props:**

- `children: ReactNode` - Your application components

#### `<EnhancedProtectedPage>`

Advanced protection with enhanced security features.

```jsx
import { EnhancedProtectedPage } from "cyshield-sdk";

<EnhancedProtectedPage
  enableBehaviorTracking={true}
  enableIPAnalysis={true}
  onThreatDetected={(threat) => console.log("Threat:", threat)}
>
  <YourApp />
</EnhancedProtectedPage>;
```

**Props:**

- `enableBehaviorTracking?: boolean` - Enable behavioral analysis (default: false)
- `enableIPAnalysis?: boolean` - Enable IP risk analysis (default: false)
- `onThreatDetected?: (threat: object) => void` - Callback when threat is detected
- `children: ReactNode` - Your application components

## 🔒 Security Features

### Automatic IP Validation

The SDK automatically validates visitor IP addresses against CyShield's threat intelligence database:

- Malicious IP detection
- Bot traffic identification
- Geolocation anomalies
- Known attack sources

### Behavioral Analysis

When enabled, the SDK monitors user behavior patterns:

- Mouse movement patterns
- Navigation patterns
- Session duration
- Interaction patterns

### Real-time Protection

- Automatic blocking of malicious traffic
- Real-time threat detection
- Continuous monitoring
- Instant security updates

## 📊 Monitoring & Analytics

All security events are automatically logged to your CyShield dashboard:

- IP validation results
- Threat detection events
- Traffic patterns
- Security incidents
- Performance metrics

Access your dashboard at [https://cyshield.dev/dashboard](https://cyshield.dev/dashboard) to view detailed analytics and configure security rules.

## 🧪 Testing

### Development Mode

For testing and development, enable debug mode:

```javascript
import { setConfig } from "cyshield-sdk";

setConfig({
  API_KEY: "your-test-api-key",
  APP_ID: "your-test-app-id",
  DEBUG: true, // Enables detailed logging
});
```

### Example Test

```javascript
import { render, screen } from "@testing-library/react";
import { ProtectedPage, setConfig } from "cyshield-sdk";
import App from "./App";

beforeEach(() => {
  setConfig({
    API_KEY: "test-key",
    APP_ID: "test-app-id",
    DEBUG: true,
  });
});

test("renders protected app", () => {
  render(
    <ProtectedPage>
      <App />
    </ProtectedPage>
  );

  expect(screen.getByText("Welcome")).toBeInTheDocument();
});
```

## 🚨 Error Handling

The SDK handles errors gracefully and provides fallback behavior:

- Network connectivity issues
- API rate limiting
- Invalid configurations
- Service unavailability

Debug mode provides detailed error information for troubleshooting.

## 🔧 Troubleshooting

### Common Issues

1. **API Key Issues**

   - Ensure your API key is valid and active
   - Check that your APP_ID matches your registered application
   - Verify credentials in your CyShield dashboard

2. **Environment Variables**

   - Make sure environment variables are properly set
   - Check that variable names match exactly (VITE_APP_FIREWALL_API_KEY, VITE_APP_FIREWALL_APP_ID)
   - Restart your development server after adding environment variables

3. **Network Issues**
   - Verify your firewall allows connections to CyShield services
   - Check CORS configuration if using in browser environments

### Debug Mode

Enable debug mode for detailed logging:

```javascript
setConfig({
  API_KEY: "your-api-key",
  APP_ID: "your-app-id",
  DEBUG: true,
  LOG_LEVEL: "debug",
});
```

## � What's Next?

Once you have the basic protection set up:

1. **Monitor Your Dashboard** - View security events and analytics
2. **Configure Rules** - Set up custom security rules for your application
3. **Optimize Settings** - Fine-tune protection based on your traffic patterns
4. **Scale Protection** - Add additional applications to your CyShield account

## 📝 Changelog

### v1.1.1

- Simplified SDK exports for better security
- Enhanced configuration options
- Improved error handling
- Performance optimizations
- Better documentation

### v1.1.0

- Added EnhancedProtectedPage component
- Real-time threat monitoring
- Behavioral analysis capabilities
- Enhanced IP validation

### v1.0.0

- Initial release
- Basic IP validation
- ProtectedPage component
- Core protection features

## 📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

## 🆘 Support

- 📖 [Documentation](https://docs.cyshield.dev)
- � [Dashboard](https://cyshield.dev/dashboard)
- � [Report Issues](mailto:support@cyshield.dev)
- 📧 [Email Support](mailto:support@cyshield.dev)

---

**CyShield SDK** - Enterprise-grade security for your React applications.