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

npm install cyshield-sdk

or

yarn add cyshield-sdk

🚀 Quick Start

Basic Protection

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

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:

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

SDK Configuration Options

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.

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.

import { ProtectedPage } from "cyshield-sdk";

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

Props:

• children: ReactNode - Your application components

<EnhancedProtectedPage>

Advanced protection with enhanced security features.

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 to view detailed analytics and configure security rules.

🧪 Testing

Development Mode

For testing and development, enable debug mode:

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

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:

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
• � Dashboard
• � Report Issues
• 📧 Email Support

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