SecureDX

 ____                           ____  __  __
/ ___|  ___  ___ _   _ _ __ ___|  _ \ \ \/ /
\___ \ / _ \/ __| | | | '__/ _ \ | | | \  / 
 ___) |  __/ (__| |_| | | |  __/ |_| | /  \ 
|____/ \___|\___|\__,_|_|  \___|____/ /_/\_\

Graduated Security Gates for DevSecOps Pipelines

SecureDX is an enterprise-grade DevSecOps tool that integrates graduated security gates directly into developer workflows. It provides static application security testing (SAST), secrets detection, Infrastructure as Code (IaC) scanning, and data residency analysis with configurable severity thresholds based on CVSS scoring.

Developed by HERO CONTROL SYSTEMS LTD, Lusaka, Zambia.

Table of Contents

1. Overview
2. Compliance Frameworks
3. System Requirements
4. Installation
5. Quick Start
6. Command Reference
7. Configuration
8. Scanner Modules
9. Language Support
10. CI/CD Integration
11. Programmatic API
12. Security Model
13. License
14. Support

Overview

SecureDX implements a graduated security gate architecture that categorises findings into three decision outcomes: BLOCK, WARN, and PASS. This approach balances security enforcement with developer productivity by allowing teams to configure thresholds appropriate to their risk tolerance.

Core Capabilities

| Capability | Description | |------------|-------------| | Static Application Security Testing (SAST) | Deep analysis for OWASP Top 10 vulnerabilities across multiple languages | | Secrets Detection | Identification of hardcoded credentials, API keys, and sensitive tokens | | Infrastructure as Code Scanning | Security analysis of Terraform, CloudFormation, Kubernetes, Dockerfile, and Ansible | | Data Residency Analysis | Geographic identification of data storage endpoints and cross-border transfer detection | | Software Bill of Materials (SBOM) | Generation of CycloneDX and SPDX compliant dependency inventories | | Technical Debt Registry | Tracking and management of deferred security findings | | Git Hook Integration | Automated scanning at pre-commit and pre-push stages | | Productivity Analytics | Local scan history and security trend analysis |

Architecture

SecureDX operates entirely locally with no external telemetry by default. All scan results, analytics, and configuration are stored within the project directory under .securedx/. The tool is designed to function in air-gapped environments and does not require network connectivity for core scanning operations.

Compliance Frameworks

SecureDX maps security findings to industry-standard compliance frameworks, enabling organisations to generate audit-ready evidence.

| Framework | Description | Coverage | |-----------|-------------|----------| | CIS Benchmarks | Center for Internet Security configuration standards | AWS, Azure, GCP, Kubernetes, Docker | | SOC 2 Type II | Service Organisation Control attestation | Security, Availability, Confidentiality | | HIPAA | Health Insurance Portability and Accountability Act | Healthcare data protection controls | | PCI-DSS | Payment Card Industry Data Security Standard | Cardholder data protection | | GDPR | General Data Protection Regulation (EU) | Personal data processing and transfer | | NIST 800-53 | National Institute of Standards and Technology | Federal security controls | | ISO 27001 | International information security standard | Information security management | | NSA/CISA | Kubernetes Hardening Guidance | Container orchestration security | | Zambia DPA 2021 | Data Protection Act No. 3 of 2021 (Zambia) | Personal data processing and cross-border transfer |

The Data Residency scanner specifically addresses Zambia Data Protection Act compliance by identifying personal data storage locations, flagging cross-border transfers, and detecting endpoints in jurisdictions without adequate data protection agreements with Zambia.

System Requirements

| Requirement | Specification | |-------------|---------------| | Node.js | Version 18.0.0 or higher | | Operating System | macOS, Linux, Windows | | Git | Version 2.x or higher (for hook integration) | | Disk Space | Minimum 50 MB for installation |

Installation

Global Installation (Recommended)

npm install -g securedx

Project-Level Installation

npm install --save-dev securedx

Verification

securedx --version

Quick Start

1. Initialise Project

securedx init

This creates a securedx.config.json configuration file and optionally installs Git hooks.

2. Run Security Scan

securedx scan

3. View Report

securedx report

Command Reference

securedx init

Initialise SecureDX in the current project directory.

securedx init              # Interactive configuration
securedx init -y           # Accept default configuration
securedx init --ci         # Configure for CI/CD environment
securedx init --no-hooks   # Skip Git hook installation

securedx scan

Execute security scans on the codebase.

securedx scan              # Full scan (all scanners)
securedx scan --staged     # Scan staged files only
securedx scan --secrets    # Secrets detection only
securedx scan --lint       # Security linting only
securedx scan --deps       # Dependency audit only
securedx scan --sast       # SAST deep analysis
securedx scan --json       # Output in JSON format
securedx scan --sarif      # Output in SARIF format

securedx iac

Scan Infrastructure as Code for security misconfigurations.

securedx iac                            # Scan current directory
securedx iac --path ./infrastructure    # Scan specific path
securedx iac --platform terraform       # Terraform files only
securedx iac --platform kubernetes      # Kubernetes manifests only
securedx iac --platform dockerfile      # Dockerfiles only
securedx iac --platform cloudformation  # CloudFormation templates only
securedx iac --platform ansible         # Ansible playbooks only
securedx iac --compliance CIS           # Filter by CIS Benchmark
securedx iac --compliance SOC2,HIPAA    # Multiple compliance frameworks
securedx iac --severity high            # High severity and above
securedx iac --json                     # JSON output
securedx iac --sarif                    # SARIF output

Supported Platforms:

| Platform | File Extensions | Description | |----------|-----------------|-------------| | Terraform | .tf, .tfvars | AWS, Azure, GCP resource definitions | | CloudFormation | .yaml, .yml, .json | AWS infrastructure templates | | Kubernetes | .yaml, .yml | Manifests and Helm charts | | Dockerfile | Dockerfile, *.dockerfile | Container image definitions | | Ansible | .yaml, .yml | Playbooks and roles |

securedx residency

Analyse data residency and geographic data distribution.

securedx residency                     # Full data residency scan
securedx residency --summary           # Summary output only
securedx residency --type database     # Database endpoints only
securedx residency --type storage      # Storage endpoints only
securedx residency --type api          # API endpoints only
securedx residency --provider aws      # AWS services only
securedx residency --provider azure    # Azure services only
securedx residency --provider gcp      # GCP services only
securedx residency --country US        # Filter by country
securedx residency --risk high         # High risk findings only
securedx residency --json              # JSON output

Detection Categories:

| Category | Services Detected | |----------|-------------------| | Databases | Amazon RDS, DynamoDB, MongoDB Atlas, Supabase, PlanetScale, Azure SQL, Cloud SQL | | Storage | Amazon S3, Azure Blob Storage, Google Cloud Storage, DigitalOcean Spaces | | APIs | API Gateway, Lambda, Azure Functions, Cloud Functions, Vercel, Netlify | | CDNs | CloudFront, Cloudflare, Azure CDN, Fastly | | Authentication | Amazon Cognito, Auth0, Okta, Firebase Auth | | Analytics | Datadog, Sentry, Mixpanel, Segment, New Relic | | Messaging | Amazon SQS, SNS, Twilio, SendGrid, Azure Service Bus |

Compliance Features:

• GDPR data residency verification (EU/EEA detection)
• Zambia DPA 2021 cross-border transfer identification
• Unknown jurisdiction flagging
• Adequacy decision verification

securedx sbom

Generate Software Bill of Materials.

securedx sbom                      # Generate CycloneDX SBOM
securedx sbom --format spdx        # Generate SPDX SBOM
securedx sbom -o sbom.json         # Save to specified file
securedx sbom --include-dev        # Include development dependencies
securedx sbom --include-licenses   # Include license text

securedx report

Generate security reports.

securedx report                       # Text report to stdout
securedx report --format html         # HTML report
securedx report --format json         # JSON export
securedx report --output report.html  # Save to file
securedx report --history --days 30   # Include historical trends

securedx hooks

Manage Git hook integration.

securedx hooks --status     # Display hook installation status
securedx hooks --install    # Install Git hooks
securedx hooks --uninstall  # Remove Git hooks

securedx debt

Manage security technical debt registry.

securedx debt --summary          # View debt summary
securedx debt --list             # List all entries
securedx debt --open             # List unresolved entries
securedx debt --resolve <id>     # Mark entry as resolved
securedx debt --accept <id>      # Accept risk for entry
securedx debt --prune            # Remove expired entries

Configuration

SecureDX is configured via securedx.config.json in the project root directory.

Configuration File Structure

{
  "gate": {
    "blockThreshold": 7.0,
    "warnThreshold": 4.0,
    "failOnBlock": true,
    "warnOnly": false
  },
  "scanners": {
    "secrets": {
      "enabled": true,
      "customPatterns": []
    },
    "lint": {
      "enabled": true
    },
    "dependencies": {
      "enabled": true
    },
    "sast": {
      "enabled": true
    }
  },
  "hooks": {
    "preCommit": {
      "enabled": true,
      "scanners": ["secrets", "lint"]
    },
    "prePush": {
      "enabled": true,
      "scanners": ["secrets", "lint", "dependencies"]
    }
  },
  "exclude": [
    "node_modules/**",
    "dist/**",
    "*.min.js"
  ]
}

Severity Thresholds

SecureDX uses CVSS (Common Vulnerability Scoring System) v3.x scores for severity classification.

| CVSS Score | Severity Level | Default Action | |------------|----------------|----------------| | 9.0 - 10.0 | CRITICAL | BLOCK | | 7.0 - 8.9 | HIGH | BLOCK | | 4.0 - 6.9 | MEDIUM | WARN | | 0.1 - 3.9 | LOW | PASS | | 0.0 | INFO | PASS |

Environment Variables

Configuration can be overridden via environment variables:

| Variable | Description | Default | |----------|-------------|---------| | SECUREDX_BLOCK_THRESHOLD | CVSS score threshold for blocking | 7.0 | | SECUREDX_WARN_THRESHOLD | CVSS score threshold for warnings | 4.0 | | SECUREDX_WARN_ONLY | Disable blocking (warnings only) | false | | SECUREDX_DISABLE_SECRETS | Disable secrets scanner | false | | SECUREDX_DISABLE_LINT | Disable lint scanner | false | | SECUREDX_DISABLE_DEPS | Disable dependency scanner | false |

Scanner Modules

Secrets Scanner

Detects hardcoded credentials and sensitive tokens using pattern matching and entropy analysis.

Detection Patterns:

| Category | Examples | |----------|----------| | Cloud Provider Keys | AWS Access Keys, Azure Client Secrets, GCP Service Account Keys | | API Tokens | GitHub PAT, GitLab tokens, Stripe API keys, Twilio credentials | | Database Credentials | Connection strings, embedded passwords | | Cryptographic Material | Private keys (RSA, ECDSA, Ed25519), SSH keys, PGP keys | | Authentication Tokens | JWT tokens, OAuth tokens, session identifiers | | Generic Secrets | High-entropy strings matching secret patterns |

Security Linter

Identifies dangerous code patterns and security anti-patterns.

Detection Rules:

| Category | Patterns Detected | |----------|-------------------| | Code Injection | eval(), new Function(), dynamic code execution | | SQL Injection | String concatenation in queries, unsanitised input | | Command Injection | Shell command construction with user input | | Cross-Site Scripting | innerHTML, document.write, dangerouslySetInnerHTML | | Insecure Deserialisation | pickle.loads(), yaml.load() without safe loader | | Transport Security | Disabled SSL verification, HTTP endpoints | | CORS Misconfiguration | Wildcard origins, credential exposure |

Dependency Scanner

Audits package dependencies against known vulnerability databases.

Supported Package Managers:

| Ecosystem | Package Manager | Audit Source | |-----------|-----------------|--------------| | JavaScript | npm, yarn, pnpm | npm audit, GitHub Advisory Database | | Python | pip, pipenv, poetry | pip-audit, PyPI Advisory Database |

SAST Scanner

Deep static analysis for OWASP Top 10 vulnerabilities.

Coverage:

• A01:2021 - Broken Access Control
• A02:2021 - Cryptographic Failures
• A03:2021 - Injection
• A04:2021 - Insecure Design
• A05:2021 - Security Misconfiguration
• A06:2021 - Vulnerable and Outdated Components
• A07:2021 - Identification and Authentication Failures
• A08:2021 - Software and Data Integrity Failures
• A09:2021 - Security Logging and Monitoring Failures
• A10:2021 - Server-Side Request Forgery

Language Support

SecureDX provides language-agnostic security scanning with enhanced support for specific ecosystems.

| Language | Secrets | Lint | Dependencies | SAST | |----------|---------|------|--------------|------| | JavaScript | Yes | Yes | Yes (npm/yarn) | Yes | | TypeScript | Yes | Yes | Yes | Yes | | Python | Yes | Yes | Yes (pip-audit) | Yes | | Java | Yes | Yes | Planned | Yes | | C# | Yes | Yes | Planned | Yes | | Go | Yes | Yes | Planned | Yes | | Ruby | Yes | Yes | Planned | Yes | | PHP | Yes | Yes | Planned | Yes | | Rust | Yes | Yes | Planned | Yes |

CI/CD Integration

GitHub Actions

name: Security Scan

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]

jobs:
  security:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install SecureDX
        run: npm install -g securedx

      - name: Run security scan
        run: securedx scan --sarif > results.sarif

      - name: Upload SARIF results
        uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: results.sarif

GitLab CI/CD

security_scan:
  stage: test
  image: node:20
  script:
    - npm install -g securedx
    - securedx scan --sarif > gl-sast-report.json
  artifacts:
    reports:
      sast: gl-sast-report.json
    expire_in: 1 week

Azure DevOps

trigger:
  - main

pool:
  vmImage: 'ubuntu-latest'

steps:
  - task: NodeTool@0
    inputs:
      versionSpec: '20.x'
    displayName: 'Install Node.js'

  - script: npm install -g securedx
    displayName: 'Install SecureDX'

  - script: securedx scan --json > $(Build.ArtifactStagingDirectory)/security-report.json
    displayName: 'Run Security Scan'

  - task: PublishBuildArtifacts@1
    inputs:
      pathToPublish: '$(Build.ArtifactStagingDirectory)/security-report.json'
      artifactName: 'SecurityReport'

Jenkins Pipeline

pipeline {
    agent {
        docker {
            image 'node:20'
        }
    }
    stages {
        stage('Security Scan') {
            steps {
                sh 'npm install -g securedx'
                sh 'securedx scan --json > security-report.json'
            }
        }
    }
    post {
        always {
            archiveArtifacts artifacts: 'security-report.json'
        }
    }
}

Programmatic API

SecureDX exports its core functionality for programmatic use.

Basic Usage

import {
  evaluateGate,
  secretsScanner,
  lintScanner,
  dependencyScanner,
  sastScanner
} from 'securedx';

async function runSecurityAnalysis(projectPath: string) {
  // Execute scanners
  const secretsFindings = await secretsScanner.scan(projectPath);
  const lintFindings = await lintScanner.scan(projectPath);
  const dependencyFindings = await dependencyScanner.scan(projectPath);

  // Combine findings
  const allFindings = [
    ...secretsFindings,
    ...lintFindings,
    ...dependencyFindings
  ];

  // Evaluate security gate
  const result = evaluateGate(allFindings, {
    blockThreshold: 7.0,
    warnThreshold: 4.0
  });

  return {
    decision: result.decision,  // 'PASS', 'WARN', or 'BLOCK'
    findings: result.findings,
    summary: result.summary
  };
}

Gate Result Interface

interface GateResult {
  decision: 'PASS' | 'WARN' | 'BLOCK';
  findings: Finding[];
  blocked: Finding[];
  warnings: Finding[];
  passed: Finding[];
  summary: string;
  executionTime: number;
  totalFindings: number;
  maxSeverity: number;
  blockThreshold: number;
  warnThreshold: number;
}

Security Model

SecureDX implements a graduated security gate model based on the principle that not all security findings warrant equal response. The system categorises findings into three decision outcomes:

| Decision | Criteria | Developer Impact | |----------|----------|------------------| | BLOCK | CVSS >= blockThreshold (default 7.0) | Commit/push prevented | | WARN | CVSS >= warnThreshold (default 4.0) | Warning displayed, operation continues | | PASS | CVSS < warnThreshold | No action required |

This model enables organisations to:

1. Prevent Critical Issues - Block deployment of high-severity vulnerabilities
2. Maintain Awareness - Warn developers of medium-severity issues without blocking
3. Track Technical Debt - Record low-severity findings for future remediation
4. Configure Risk Tolerance - Adjust thresholds per project or environment

Data Handling

• All scan data is stored locally in .securedx/ directory
• No telemetry or external data transmission by default
• Analytics data never leaves the local filesystem
• Suitable for air-gapped and regulated environments

License

SecureDX is distributed under a proprietary Enterprise License.

Permitted Uses:

• Internal security scanning for code analysis
• Installation on systems owned or controlled by the licensee
• Integration into internal CI/CD pipelines

Restrictions:

• No redistribution, sublicensing, or resale
• No reverse engineering, decompilation, or source code derivation
• No modification or creation of derivative works without written consent

For complete license terms, see the LICENSE.md file included with this distribution.

For licensing enquiries, contact: [email protected]

Support

Technical Support: [email protected]

Documentation: https://hcsys.co/securedx

Bug Reports: Submit via email with reproduction steps and scan output

Copyright 2025-2026 HERO CONTROL SYSTEMS LTD. All rights reserved.

Lusaka, Zambia