@ayurak/sdk 1.0.0

package/README.md

@@ -0,0 +1,370 @@
+# Aribot JavaScript/TypeScript SDK
+
+Official JavaScript SDK for the Aribot Security Platform.
+
+## Installation
+
+```bash
+npm install aribot-sdk
+# or
+yarn add aribot-sdk
+# or
+pnpm add aribot-sdk
+```
+
+## Quick Start
+
+```typescript
+import { Aribot } from 'aribot-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
+
+## API Reference
+
+### Threat Modeling
+
+```typescript
+// 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
+
+```typescript
+// 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
+
+```typescript
+// 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
+
+```typescript
+// 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);
+```
+
+## Error Handling
+
+```typescript
+import {
+  Aribot,
+  AribotError,
+  AuthenticationError,
+  RateLimitError,
+  ValidationError,
+  NotFoundError,
+  ServerError
+} from 'aribot-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
+
+```typescript
+// 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:
+
+```typescript
+import { Aribot } from 'aribot-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
+
+```typescript
+import { Aribot } from 'aribot-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
+
+```yaml
+- 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 }}
+```
+
+## Support
+
+- Documentation: https://developer.ayurak.com/docs/js-sdk
+- API Reference: https://developer.ayurak.com/api
+- Issues: https://github.com/Aristiun/aribot-js/issues
+
+## License
+
+MIT