Aribot JavaScript/TypeScript SDK

Official JavaScript SDK for the Aribot Security Platform by Aristiun & Ayurak.

Installation

npm install @ayurak/sdk
# or
yarn add @ayurak/sdk
# or
pnpm add @ayurak/sdk

Quick Start

import { Aribot } from '@ayurak/sdk';

const client = new Aribot('your_api_key');

// Analyze architecture diagram for threats
const file = new File([buffer], 'architecture.png', { type: 'image/png' });
const result = await client.threatModeling.analyzeDiagram(file);
console.log(`Found ${result.threat_count} threats`);

// Get detailed threats
const threats = await client.threatModeling.getThreats(result.diagram_id);
for (const threat of threats) {
  console.log(`[${threat.severity}] ${threat.title}`);
}

Features

• Full TypeScript support with comprehensive type definitions
• Threat Modeling - Upload diagrams, detect components, identify threats
• Compliance Scanning - ISO 27001, SOC2, GDPR, HIPAA, PCI-DSS, NIST
• Cloud Security - Scan AWS, Azure, GCP for misconfigurations
• Pipeline Security - SAST, SCA, secrets detection in CI/CD
• Digital Twin - Cloud resource mapping, health monitoring, live status
• Economics - Cost analysis, ROI calculations, market intelligence
• Red Team - Attack simulations, methodologies, threat intelligence

API Reference

Threat Modeling

// Upload and analyze a diagram
const result = await client.threatModeling.analyzeDiagram(file, {
  analysisDepth: 'comprehensive', // basic, comprehensive, detailed
  wait: true,                     // wait for analysis to complete
  timeout: 300000                 // max wait time in ms
});

// List diagrams
const diagrams = await client.threatModeling.list({ page: 1, limit: 25 });

// Get diagram details
const diagram = await client.threatModeling.get(diagramId);

// Get threats for a diagram
const threats = await client.threatModeling.getThreats(diagramId);

// Get detected components
const components = await client.threatModeling.getComponents(diagramId);

// Run AI-powered analysis
const aiResult = await client.threatModeling.analyzeWithAI(diagramId, [
  'attack_paths',
  'data_flow'
]);

// Delete a diagram
await client.threatModeling.delete(diagramId);

// Get dashboard metrics
const dashboard = await client.threatModeling.dashboard('month');

Compliance Scanning

// Run compliance scan
const result = await client.compliance.scan(diagramId, {
  standards: ['ISO27001', 'SOC2', 'GDPR'],
  includeRecommendations: true
});
console.log(`Compliance score: ${result.overall_score}%`);

// Get compliance report
const report = await client.compliance.getReport(diagramId, 'json');

// List available standards
const standards = await client.compliance.listStandards();

// Get standard details
const iso = await client.compliance.getStandard('ISO27001');

// List controls for a standard
const controls = await client.compliance.listControls('SOC2', 'access_control');

// Get compliance gaps
const gaps = await client.compliance.getGaps(diagramId, 'ISO27001');

// Create custom standard
const custom = await client.compliance.addCustomStandard(
  'Internal Security Policy',
  'Company security requirements',
  [
    {
      id: 'ISP-001',
      name: 'Data Encryption',
      description: 'All data must be encrypted at rest',
      severity: 'high'
    }
  ]
);

// Get compliance dashboard
const dashboard = await client.compliance.dashboard('quarter');

Cloud Security

// Run cloud security scan
const scan = await client.cloud.scan('123456789012', {
  provider: 'aws',
  services: ['iam', 's3', 'ec2'],
  complianceStandards: ['CIS-AWS']
});

// Get scan results
const scanResult = await client.cloud.getScan(scanId);

// List scans
const scans = await client.cloud.listScans({
  provider: 'aws',
  status: 'completed'
});

// Get findings
const findings = await client.cloud.getFindings(scanId, {
  severity: 'critical',
  service: 's3'
});

// Connect AWS account
const account = await client.cloud.connectAccount(
  'aws',
  {
    role_arn: 'arn:aws:iam::123456789012:role/AribotSecurityRole',
    external_id: 'your-external-id'
  },
  { name: 'Production AWS' }
);

// Connect GCP project
const gcpAccount = await client.cloud.connectAccount(
  'gcp',
  {
    service_account_key: '{ ... }',
    project_id: 'my-project-123'
  }
);

// List connected accounts
const accounts = await client.cloud.listAccounts('aws');

// Get remediation steps
const remediation = await client.cloud.getRemediation(findingId);

// Resolve a finding
await client.cloud.resolveFinding(findingId, 'fixed', 'Patched in v1.2.3');

// Suppress a finding
await client.cloud.suppressFinding(findingId, 'Accepted risk', 90);

// Get cloud security dashboard
const dashboard = await client.cloud.dashboard('123456789012');

Pipeline Security

// Create a project
const project = await client.pipeline.createProject('my-api', {
  repositoryUrl: 'https://github.com/org/my-api',
  scanTypes: ['sast', 'sca', 'secrets']
});

// Run security scan
const result = await client.pipeline.scan(projectId, {
  commitSha: 'abc123def456',
  branch: 'main',
  scanTypes: ['sast', 'sca', 'secrets'],
  failOnSeverity: 'high',
  wait: true
});

if (result.status === 'failed') {
  console.log('Security gate failed!');
  for (const finding of result.blocking_findings || []) {
    console.log(`  [${finding.severity}] ${finding.title}`);
  }
}

// Get scan details
const scan = await client.pipeline.getScan(scanId);

// Get specific finding types
const sastFindings = await client.pipeline.getSastFindings(scanId);
const scaFindings = await client.pipeline.getScaFindings(scanId);
const secrets = await client.pipeline.getSecretsFindings(scanId);

// Configure security gates
await client.pipeline.configureGates(projectId, {
  fail_on_critical: true,
  fail_on_high: true,
  max_high_findings: 5,
  block_secrets: true,
  required_scan_types: ['sast', 'secrets']
});

// Set baseline (suppress existing findings)
await client.pipeline.addBaseline(projectId, scanId);

// Suppress a finding
await client.pipeline.suppressFinding(findingId, 'False positive');

// Get pipeline dashboard
const dashboard = await client.pipeline.dashboard(projectId);

Digital Twin

// Get cloud providers
const providers = await client.digitalTwin.getProviders();
// Returns: [{ name: 'aws', display_name: 'Amazon Web Services', is_active: true }, ...]

// Get available resources
const resources = await client.digitalTwin.getResources({ provider: 'aws', limit: 50 });

// Get health status
const health = await client.digitalTwin.getHealth();

// Get analytics
const analytics = await client.digitalTwin.getAnalytics();

// Get diagram component cloud status
const status = await client.digitalTwin.getDiagramComponentStatus(diagramId);

// Map component to cloud resource
await client.digitalTwin.mapComponent(diagramId, componentId, resourceId);

// Sync diagram status
await client.digitalTwin.syncDiagramStatus(diagramId);

Economics

// Get economics dashboard
const dashboard = await client.economics.getDashboard({ period: 'month' });

// Get diagram cost analysis
const cost = await client.economics.getDiagramCostAnalysis(diagramId);
console.log(`Monthly cost: $${cost.total_monthly_cost}`);

// Get component cost
const componentCost = await client.economics.getComponentCost(componentId);

// Get economic intelligence (includes Strategic Cost Optimization)
const intel = await client.economics.getEconomicIntelligence();
// Returns: { status: 'success', provider: 'aws', pricing: {...},
//           strategic_optimization: { current: {...}, previous: {...} } }

// Refresh Strategic Cost Optimization recommendations (AI-powered)
// Moves current recommendations to "previous" and generates new ones
const refresh = await client.economics.refreshRecommendations();
// Returns: { status: 'success', message: 'Recommendations refreshed',
//           current: {...}, previous: {...} }

// Get market intelligence
const market = await client.economics.getMarketIntelligence();

// Calculate ROI
const roi = await client.economics.calculateROI({
  investment: 100000,
  risksAddressed: ['risk-1', 'risk-2'],
  timeframeDays: 365
});
console.log(`ROI: ${roi.roi_percentage}%`);

Red Team

// Get methodologies
const methodologies = await client.redTeam.getMethodologies();
// Returns: [{ id: 'stride', name: 'STRIDE', description: '...' }, ...]

// Get simulations
const simulations = await client.redTeam.getSimulations({ limit: 10 });

// Get threat intelligence
const intel = await client.redTeam.getIntelligence();

// Generate attack paths
const paths = await client.redTeam.generateAttackPaths(diagramId, {
  depth: 'comprehensive',
  includeRemediations: true
});

// Get security requirements
const requirements = await client.redTeam.getSecurityRequirements(diagramId);

Severity Assignment (AI-powered)

// Estimate AI cost for severity assignment
const estimate = await client.compliance.estimateSeverityCost({
  scanId: scanId,
  accountId: accountId
});
// Returns: { estimated_tokens: 15000, estimated_cost_usd: 0.45, violations_count: 150 }

// Assign severity using AI (automatically analyzes all violations)
const result = await client.compliance.assignSeverityAI({
  scanId: scanId,
  accountId: accountId,
  model: 'claude-3-sonnet', // or 'gpt-4', 'gemini-pro'
  batchSize: 50
});
// Returns: { status: 'completed', processed: 150, updated: 142, errors: 0 }

// Manually assign severity to violations
const manualResult = await client.compliance.assignSeverityManual({
  violationIds: ['v-123', 'v-456'],
  severity: 'high' // critical, high, medium, low, info
});
// Returns: { updated: 2, violations: [...] }

Scanner Rules

// List scanner rules
const rules = await client.compliance.listScannerRules({
  severity: 'critical',
  provider: 'aws'
});
// Returns: [{ id: '...', name: 'S3 Public Access', severity: 'critical' }, ...]

// Get scanner rule statistics
const stats = await client.compliance.getScannerStatistics();
// Returns: { total_rules: 500, by_severity: {...}, by_provider: {...} }

// Sync rules from cloud providers
const syncResult = await client.compliance.syncScannerRules({
  providers: ['aws', 'azure', 'gcp']
});
// Returns: { synced: 150, new: 25, updated: 10 }

// Create custom scanner rule
const rule = await client.compliance.createScannerRule({
  name: 'Custom S3 Encryption Check',
  description: 'Ensure all S3 buckets have encryption enabled',
  severity: 'high',
  provider: 'aws',
  resourceType: 's3_bucket',
  condition: {
    field: 'encryption.enabled',
    operator: 'equals',
    value: true
  }
});

Dynamic Cloud Scanning

// Execute dynamic scan on cloud account
const scan = await client.compliance.executeDynamicScan({
  accountId: accountId,
  scanType: 'full', // full, quick, targeted
  resources: ['ec2', 's3', 'iam'],
  standards: ['CIS-AWS', 'SOC2']
});
// Returns: { scan_id: '...', status: 'running', estimated_duration: 300 }

// Execute unified scan with flexible scope
const unifiedScan = await client.compliance.executeUnifiedScan({
  scope: 'account', // account, standard, diagram
  scopeId: accountId,
  includeRemediation: true
});
// Returns: { scan_id: '...', status: 'queued' }

Remediation Execution

// Preview remediation before execution
const preview = await client.compliance.previewRemediation({
  policyId: policyId,
  accountId: accountId
});
// Returns: { actions: [...], risk_level: 'low', affected_resources: 5 }

// Execute remediation
const result = await client.compliance.executeRemediation({
  policyId: policyId,
  accountId: accountId,
  dryRun: false,
  autoApprove: true
});
// Returns: { status: 'completed', resources_fixed: 5, rollback_available: true }

AI Agents & Self-Healing

// Get AI agent status
const status = await client.aiAgents.getStatus();
// Returns: { active: true, agents: [...], capabilities: [...] }

// Run specialist agent analysis
const analysis = await client.aiAgents.runSpecialist({
  agentType: 'security', // security, compliance, cost, architecture
  diagramId: diagramId
});

// Self-healing operations
const healingStatus = await client.aiAgents.getSelfHealingStatus();
// Returns: { enabled: true, recent_actions: [...], autonomy_level: 'supervised' }

// Get autonomy stats
const autonomyStats = await client.aiAgents.getAutonomyStats();
// Returns: { total_remediations: 150, auto_approved: 120, manual_review: 30 }

// Trigger remediation
const remediation = await client.aiAgents.triggerRemediation({
  findingId: findingId,
  autoApprove: false
});

// Approve/reject remediation action
await client.aiAgents.approveRemediation(remediationId);
await client.aiAgents.rejectRemediation(remediationId, 'Risk too high');

// Rollback remediation
await client.aiAgents.rollbackRemediation(remediationId);

// Emergency stop all autonomous actions
await client.aiAgents.emergencyStop();

// Resume autonomous operations
await client.aiAgents.resumeOperations();

Security Co-Pilot

// Get security co-pilot status
const status = await client.securityCopilot.getStatus();
// Returns: { enabled: true, mode: 'supervised', active_threats: 5 }

// Get pending actions awaiting approval
const actions = await client.securityCopilot.getPendingActions();
// Returns: [{ id: '...', type: 'patch', resource: '...', risk: 'low' }, ...]

// Get action history
const history = await client.securityCopilot.getActionHistory({ limit: 50 });

// Get active threats
const threats = await client.securityCopilot.getActiveThreats();

// Approve/reject action
await client.securityCopilot.approveAction(actionId);
await client.securityCopilot.rejectAction(actionId);

// Rollback action
await client.securityCopilot.rollbackAction(actionId);

// Trigger security scan
const scan = await client.securityCopilot.triggerScan({ scope: 'full' });

// Update settings
await client.securityCopilot.updateSettings({
  autoRemediation: true,
  maxRiskLevel: 'medium'
});

// Toggle co-pilot on/off
await client.securityCopilot.toggle(true);

Presets Import

// Import compliance presets
const presets = await client.compliance.importPresets({
  provider: 'aws', // aws, azure, gcp, all
  categories: ['security', 'cost', 'operations']
});
// Returns: { imported: 50, standards: [...], rules: [...] }

Strategic Remediation Plan (AI-powered)

// Generate strategic remediation plan for a severity level
// Uses AI to analyze all violations and create a comprehensive plan
const plan = await client.compliance.generateStrategicPlan({
  scanId: scanId,
  accountId: accountId,
  severity: 'critical' // critical, high, medium, low
});
// Returns: {
//   id: 'uuid',
//   severity: 'critical',
//   status: 'generated',
//   overview: 'Strategic overview of all critical violations...',
//   rootCauses: [{ cause: '...', theme: '...', impact: '...' }],
//   groupedViolations: [{ policy: '...', violations: [...] }],
//   highImpactActions: [{ action: '...', impactScore: 95 }],
//   remediationPhases: [{ phase: 1, duration: '1 week', actions: [...] }],
//   successMetrics: [{ metric: '...', target: '...' }],
//   estimatedTotalEffort: '2-3 weeks',
//   costSavingsFinops: { monthly: 5000, annual: 60000 },
//   costSavingsRisk: { riskReduction: '85%', avoidedIncidents: 12 }
// }

// Get existing strategic plan
const existing = await client.compliance.getStrategicPlan(planId);

// List strategic plans for an account
const plans = await client.compliance.listStrategicPlans({
  accountId: accountId,
  severity: 'critical'
});

Mitigation Plan (AI-powered)

// Get existing mitigation plan for a diagram
const plan = await client.threatModeling.getMitigationPlan(diagramId);
if (plan) {
  console.log(`Overview: ${plan.plan.overview}`);
  console.log(`Recommendations: ${plan.plan.recommendations.length}`);
  plan.plan.recommendations.forEach(rec => {
    console.log(`  [${rec.rank}] ${rec.title} - ${rec.priority}`);
  });
}

// Generate new mitigation plan (AI-powered, uses chunked processing)
const newPlan = await client.threatModeling.generateMitigationPlan(diagramId, {
  forceRegenerate: true  // Force regenerate even if cached
});
// Returns comprehensive plan with:
// - overview: Strategic summary of all threats
// - recommendations: Ranked list with code snippets
// - rootCauses: Identified patterns across threats
// - remediationPhases: Phased approach with timelines
// - successMetrics: Measurable criteria
// - metadata: AI provider, generation time, etc.

console.log(`Generated in ${newPlan.plan.metadata.generationTimeMs}ms`);
console.log(`Threats analyzed: ${newPlan.plan.metadata.threatCount}`);

// Access recommendations with code snippets
newPlan.plan.recommendations.forEach(rec => {
  console.log(`[${rec.priority}] ${rec.title}`);
  console.log(`  Impact: ${rec.impact}`);
  console.log(`  Effort: ${rec.effort}`);
  console.log(`  Affected threats: ${rec.affectedThreats?.join(', ')}`);
  if (rec.codeSnippet) {
    console.log(`  Code (${rec.codeLanguage}):`);
    console.log(`    ${rec.codeSnippet}`);
  }
});

// View root causes (patterns identified across multiple threats)
newPlan.plan.rootCauses.forEach(cause => {
  console.log(`Root cause: ${cause.cause}`);
  console.log(`  Theme: ${cause.theme}, Impact: ${cause.impact}`);
});

// View phased remediation plan
newPlan.plan.remediationPhases.forEach(phase => {
  console.log(`Phase: ${phase.phase} (${phase.duration})`);
  console.log(`  Actions: ${phase.actions.join(', ')}`);
  console.log(`  Threats resolved: ${phase.threatsResolved}`);
});

// Update plan with manual edits
const updatedPlan = { ...newPlan.plan };
updatedPlan.recommendations[0].priority = 'immediate';
await client.threatModeling.updateMitigationPlan(diagramId, updatedPlan);

Error Handling

import {
  Aribot,
  AribotError,
  AuthenticationError,
  RateLimitError,
  ValidationError,
  NotFoundError,
  ServerError
} from '@ayurak/sdk';

const client = new Aribot('your_api_key');

try {
  const result = await client.threatModeling.analyzeDiagram(file);
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error('Invalid API key');
  } else if (error instanceof RateLimitError) {
    console.error(`Rate limited. Retry after ${error.retryAfter} seconds`);
  } else if (error instanceof ValidationError) {
    console.error(`Invalid request: ${error.errors}`);
  } else if (error instanceof NotFoundError) {
    console.error('Resource not found');
  } else if (error instanceof ServerError) {
    console.error('Server error - try again later');
  } else if (error instanceof AribotError) {
    console.error(`API error: ${error.message}`);
  }
}

Configuration

// Custom base URL (for on-premise deployments)
const client = new Aribot('your_api_key', {
  baseUrl: 'https://aribot.internal.company.com/api',
  timeout: 60000
});

// Check API health
const health = await client.health();

// Get current user info
const user = await client.me();

// Get usage stats
const usage = await client.usage('month');
console.log(`API calls used: ${usage.calls_used}/${usage.calls_limit}`);

Node.js Usage

For Node.js environments, you can use the fs module to read files:

import { Aribot } from '@ayurak/sdk';
import { readFileSync } from 'fs';

const client = new Aribot(process.env.ARIBOT_API_KEY!);

// Read file and create Blob
const buffer = readFileSync('architecture.png');
const blob = new Blob([buffer], { type: 'image/png' });

const result = await client.threatModeling.analyzeDiagram(blob, {
  filename: 'architecture.png'
});

Browser Usage

import { Aribot } from '@ayurak/sdk';

const client = new Aribot('your_api_key');

// Handle file input
const input = document.querySelector<HTMLInputElement>('#file-input');
input?.addEventListener('change', async (e) => {
  const file = (e.target as HTMLInputElement).files?.[0];
  if (file) {
    const result = await client.threatModeling.analyzeDiagram(file);
    console.log(result);
  }
});

CI/CD Integration

GitHub Actions

- name: Security Scan
  uses: actions/setup-node@v4
  with:
    node-version: '20'

- run: |
    npm install aribot-sdk
    node << 'EOF'
    const { Aribot } = require('aribot-sdk');

    const client = new Aribot(process.env.ARIBOT_API_KEY);

    (async () => {
      const result = await client.pipeline.scan(
        process.env.PROJECT_ID,
        {
          commitSha: process.env.GITHUB_SHA,
          failOnSeverity: 'high',
          wait: true
        }
      );

      if (result.status === 'failed') {
        process.exit(1);
      }
    })();
    EOF
  env:
    ARIBOT_API_KEY: ${{ secrets.ARIBOT_API_KEY }}
    PROJECT_ID: ${{ vars.PROJECT_ID }}

Changelog

v1.5.0

• Added: Strategic Remediation Plan API (client.compliance.generateStrategicPlan, getStrategicPlan, listStrategicPlans) - AI-powered strategic planning for compliance violations with cost savings analysis
• Added: Economic Intelligence Refresh (client.economics.refreshRecommendations) - Refresh AI-powered cost optimization recommendations
• Added: Severity Assignment API (client.compliance.estimateSeverityCost, assignSeverityAI, assignSeverityManual)
• Added: Scanner Rules API (client.compliance.listScannerRules, getScannerStatistics, syncScannerRules, createScannerRule)
• Added: Dynamic Cloud Scanning (client.compliance.executeDynamicScan, executeUnifiedScan)
• Added: Remediation Execution (client.compliance.previewRemediation, executeRemediation)
• Added: AI Agents & Self-Healing module (client.aiAgents) with autonomous remediation
• Added: Security Co-Pilot module (client.securityCopilot) for supervised security operations
• Added: Presets Import (client.compliance.importPresets)
• Added: Mitigation Plan API (client.threatModeling.getMitigationPlan, generateMitigationPlan, updateMitigationPlan) - AI-powered strategic remediation planning with chunked processing

v1.4.0

• Fixed: Base URL corrected from api.aribot.aristiun.com to api.aribot.ayurak.com
• Added: AI module (client.ai) - usage, quota, models, configure, analyze, queue status
• Added: SBOM module (client.sbom) - document management, upload, vulnerability scanning
• Added: Dashboard module (client.dashboard) - overview, recent activity, risk summary
• Added: FinOps module (client.finops) - cost optimization, recommendations, cost breakdown
• Added: Marketplace module (client.marketplace) - templates, categories, featured items
• Added: API Keys module (client.apiKeys) - list, create, revoke API keys
• Added: Framework-specific compliance scoring support

Support

• Documentation: https://developer.ayurak.com/docs/js-sdk
• API Reference: https://developer.ayurak.com/api
• Issues: https://github.com/ayurak/aribot-js/issues

License

MIT