@fireshield/rules-engine

An independent rules engine for security analysis of Firebase and cloud projects. This package provides a Firebase-agnostic rules execution engine that can analyze project configurations against security policies.

Features

• Firebase-Independent: No Firebase dependencies, can be used with any project configuration data
• Rules Engine: Powered by json-rules-engine for flexible condition evaluation
• SARIF Output: Generate industry-standard SARIF reports for security findings
• Extensible Scanners: Plugin architecture for custom security scanners
• TypeScript: Full TypeScript support with comprehensive type definitions

Installation

From GitHub Packages

# Configure npm to use GitHub Packages for @fireshield scope
echo "@fireshield:registry=https://npm.pkg.github.com" >> ~/.npmrc

# Install the package
npm install @fireshield/rules-engine

Alternative: Using .npmrc file

Create a .npmrc file in your project root:

@fireshield:registry=https://npm.pkg.github.com

Then install:

npm install @fireshield/rules-engine

Authentication

For private packages, you'll need a GitHub Personal Access Token with read:packages permission:

echo "//npm.pkg.github.com/:_authToken=YOUR_GITHUB_TOKEN" >> ~/.npmrc

Basic Usage

import { 
  executeRules, 
  createRuleExecutionContext, 
  generateSARIF 
} from '@fireshield/rules-engine';

// Your project information
const projectInfo = {
  project_id: 'my-project',
  auth: { auth_enabled: false },
  databases: [{ id: 'default', location: 'us-central1' }],
  appcheck: { 
    app_check_enabled: true,
    total_apps: 2,
    total_services: 3,
    enforced_services: 2
  },
  // ... other project data
};

// Your security rules
const rules = [
  {
    id: 'auth-not-enabled',
    name: 'Authentication Not Enabled',
    description: 'Checks if Firebase Authentication is enabled',
    severity: 'high',
    category: 'Authentication',
    conditions: {
      all: [{ fact: 'auth', path: 'auth_enabled', operator: 'equal', value: false }]
    },
    event: {
      type: 'auth-not-enabled',
      params: { message: 'Firebase Authentication is not enabled' }
    }
  }
];

// Execute rules - ProjectInformation is automatically enriched with computed properties
const context = createRuleExecutionContext(projectInfo, rules);
const results = await executeRules(context);

// Generate SARIF report
const analysisResult = {
  scanId: 'scan-123',
  project_id: 'my-project',
  timestamp: new Date().toISOString(),
  total_rules: rules.length,
  triggered_rules: results.filter(r => r.triggered).length,
  results: results
};

const sarifReport = generateSARIF(analysisResult);

Core Types

ProjectInformation

The core data structure containing Firebase project configuration. ProjectInformation is automatically enriched with computed properties during rule execution.

interface ProjectInformation {
  project_id: string;
  databases: DatabaseInfo[];
  functionsv1: FirebaseFunction[];
  functionsv2: FirebaseFunction[];
  storage_buckets: StorageBucket[];
  auth: AuthSettings;
  appcheck: AppCheckSettings;
  function_secrets: SecretScanResult[];
}

// Enriched with computed properties during execution
interface EnrichedProjectInformation extends ProjectInformation {
  computed: {
    enforcement_ratio: number;
    apps_without_attestation_providers: number;
    security_score: number;
    has_secrets: boolean;
    multi_region_deployment: boolean;
  };
}

StaticRule

interface StaticRule {
  id: string;
  name: string;
  description: string;
  severity?: 'low' | 'medium' | 'high' | 'critical';
  category?: string;
  conditions: Record<string, unknown>;
  event: {
    type: string;
    params: {
      message: string;
      [key: string]: unknown;
    };
  };
}

RuleResult

interface RuleResult {
  rule_id: string;
  rule_name: string;
  severity: string;
  category: string;
  message: string;
  triggered: boolean;
  facts_used: Record<string, unknown>;
  event_params?: Record<string, unknown>;
}

API Reference

Core Functions

executeRules(context: RuleExecutionContext): Promise<RuleResult[]>

Executes security rules against project information.

createRuleExecutionContext(projectInfo: ProjectInformation, rules: StaticRule[]): RuleExecutionContext

Creates an execution context for rule evaluation.

generateSARIF(analysisResult: AnalysisResult): any

Generates SARIF (Static Analysis Results Interchange Format) output.

Scanners

The package includes extensible scanners for different security aspects:

• Secret Scanner: Detects hardcoded secrets in function environment variables
• Authentication Scanner: Analyzes authentication configuration
• Access Control Scanner: Reviews database and storage permissions
• Configuration Scanner: Validates security settings

Rule Examples

Computed Properties

The rules engine automatically enriches ProjectInformation with computed properties that provide calculated values for complex security analysis:

// Available computed properties:
{
  computed: {
    enforcement_ratio: number;           // Ratio of enforced AppCheck services
    apps_without_attestation_providers: number; // Count of apps missing attestation
    security_score: number;             // Overall security score (0-100)
    has_secrets: boolean;               // Whether functions contain secrets
    multi_region_deployment: boolean;   // Whether deployment spans multiple regions
  }
}

Rule Path Reference

| ProjectInformation Path | Description | Example Value | | ---------------------------- | --------------------------------------- | ------------- | | auth.auth_enabled | Whether authentication is enabled | true | | auth.email_enabled | Whether email authentication is enabled | true | | auth.password_min_length | Minimum password length | 8 | | appcheck.app_check_enabled | Whether App Check is enabled | true | | appcheck.total_apps | Total number of apps | 3 | | appcheck.total_services | Total number of services | 5 | | appcheck.enforced_services | Number of enforced services | 3 | | computed.enforcement_ratio | Enforcement coverage ratio | 0.6 | | computed.has_secrets | Whether secrets were detected | false |

Rule Examples

Authentication Rules

{
  id: 'weak-password-policy',
  name: 'Weak Password Policy',
  description: 'Checks for weak password policies',
  severity: 'medium',
  category: 'Authentication',
  conditions: {
    all: [
      { fact: 'auth', path: 'auth_enabled', operator: 'equal', value: true },
      { fact: 'auth', path: 'password_min_length', operator: 'lessThan', value: 8 }
    ]
  },
  event: {
    type: 'weak-password-policy',
    params: { message: 'Password policy is weak' }
  }
}

App Check Rules

{
  id: 'low-enforcement-coverage',
  name: 'Low App Check Enforcement Coverage',
  description: 'Less than 50% of services have App Check enforcement enabled',
  severity: 'warning',
  category: 'AppCheck',
  conditions: {
    all: [
      { fact: 'computed', path: 'enforcement_ratio', operator: 'lessThan', value: 0.5 }
    ]
  },
  event: {
    type: 'low-enforcement-coverage',
    params: { message: 'App Check enforcement coverage is too low' }
  }
}

Function Security Rules

{
  id: 'functions-have-secrets',
  name: 'Functions Contain Secrets',
  description: 'Detects hardcoded secrets in function environment variables',
  severity: 'critical',
  category: 'Secrets',
  conditions: {
    all: [{ fact: 'computed', path: 'has_secrets', operator: 'equal', value: true }]
  },
  event: {
    type: 'functions-have-secrets',
    params: { message: 'Functions contain hardcoded secrets' }
  }
}

Development Status

🚧 This package is under active development as part of the Fireshield rules engine extraction.

Implementation Stages

• ✅ Stage 1: Package structure, types, and configuration
• ✅ Stage 2: Core logic extraction (fact-transformer migration to computed properties)
• ✅ Stage 3: Rules engine modernization and ProjectInformation integration
• ⏳ Stage 4: Scanner integration
• ⏳ Stage 5: Testing and validation
• ⏳ Stage 6: Documentation and examples

Migration Notes

Fact-Transformer Deprecation (June 2025)

• ✅ Removed fact-transformer layer for simplified architecture
• ✅ Direct ProjectInformation usage with computed properties
• ✅ Enhanced type safety and performance
• ✅ All 26 rules migrated to new format

For legacy systems still using fact-transformer functions, please update to use executeRules() directly with ProjectInformation objects.

Contributing

This package is part of the Fireshield project. Contributions are welcome!

License

MIT License - see LICENSE file for details.

Support

For issues and questions:

• GitHub Issues: Fireshield Issues
• Documentation: Fireshield Docs

Part of the Fireshield Security Platform

Publishing to GitHub Packages

To publish this package to a private GitHub npm repository, follow these steps:

1. Create a Personal Access Token (PAT)

• Go to your GitHub account settings.
• Navigate to "Developer settings" > "Personal access tokens" > "Tokens (classic)".
• Click "Generate new token" (or "Generate new token (classic)").
• Give your token a descriptive name (e.g., npm-publish).
• Select the scopes read:packages and write:packages.
• Click "Generate token" and copy the token. You will not be able to see it again.

2. Configure npm

Create or edit the .npmrc file in your user's home directory (e.g., ~/.npmrc on Linux/macOS or C:\Users\YOUR_USERNAME\.npmrc on Windows). Add the following line, replacing YOUR_PAT_HERE with the PAT you just created:

//npm.pkg.github.com/:_authToken=YOUR_PAT_HERE

This tells npm to authenticate with your PAT when interacting with the GitHub Packages registry.

3. Update package.json

Ensure your package.json file includes the repository field and a publishConfig field pointing to the GitHub Packages registry. Replace OWNER and REPO with your GitHub username or organization name and the repository name.

{
  "name": "@OWNER/rules-engine", // It's good practice to scope your package name to your GitHub owner
  // ... other package.json fields
  "repository": {
    "type": "git",
    "url": "https://github.com/OWNER/REPO.git"
  },
  "publishConfig": {
    "registry": "https://npm.pkg.github.com/"
  }
  // ...
}

Note: For this specific package, the name is @fireshield/rules-engine. If you are publishing to a personal fork or a different organization, you would change fireshield in the name property to your GitHub username or organization name (e.g., @YOUR_USERNAME/rules-engine).

4. Publish the Package

Once your PAT is configured and package.json is updated, you can publish the package using:

npm publish

This command will build your package (if a prepublishOnly script is defined) and upload it to the GitHub Packages registry associated with the repository specified in your package.json.