MobSF Integration

note

First time using MobSF? Please refer to the following documentation.

Introduction

Import your Mobile Security Framework (MobSF) security analysis reports into Conviso Platform. This integration automatically processes Android and iOS application security reports and creates security findings.

Features

• Report Import: Import MobSF JSON reports via GraphQL mutation
• Automatic Processing: Asynchronous processing of security findings
• Asset Management: Automatically creates or links assets based on app name
• SBOM Support: Automatically imports Software Bill of Materials (SBOM) data when available
• Finding Mapping: Maps MobSF findings to Conviso Platform format with proper severity levels
• Status Tracking: Track import status and processing results
• Multi-Platform: Supports both Android (APK) and iOS (IPA) applications
• Severity Mapping: Automatically maps MobSF severity buckets (high, warning, info, secure, hotspot) to Conviso severity levels

Prerequisites

• A Conviso Platform account
• A valid Conviso API Key
• MobSF JSON report file (generated from MobSF analysis)
• Access to the target company/scope in Conviso Platform
• Permission to create or update assets and findings

Setup

Authentication

The integration uses GraphQL API authentication. Ensure you have:

1. A valid Conviso API Key
2. Proper permissions to access the target company/scope
3. Asset creation/update permissions (if using automatic asset creation)

GraphQL Endpoint

The integration uses the Conviso Platform GraphQL API endpoint:

POST /graphql

Configuration

Required Parameters

The importMobsf mutation accepts the following parameters:

• file (required): The MobSF JSON report file (Upload type)
• asset_id (optional): ID of an existing asset to associate the report with
• company_id (optional): ID of the company/scope. Required if asset_id is not provided

Asset Configuration

You can configure the import in two ways:

• Provide company_id only: The system will use the app_name from your MobSF report to automatically find or create an asset
• Provide asset_id only: Use a specific asset that you've already created in Conviso Platform

important

When providing only company_id, your MobSF report must contain an app_name field. If app_name is missing, the import will fail.

Quickstart

1. Generate MobSF Report

First, analyze your mobile application with MobSF and export the JSON report.

2. Import via GraphQL

Use the importMobsf mutation to import your report:

mutation ImportMobsf($file: Upload!, $companyId: ID) {
  importMobsf(
    input: {
      file: $file
      company_id: $companyId
    }
  ) {
    controlSyncStatus {
      id
      status
      asset {
        id
        name
      }
    }
    errors
  }
}

3. Check Import Status

Monitor the import status using the returned status information:

query GetImportStatus($id: ID!) {
  controlSyncStatus(id: $id) {
    id
    status
    externalVulnerabilityCount
    importedVulnerabilityCount
    createdVulnerabilityCount
    successCount
    failureCount
    failureReason
    estimatedDurationInSeconds
  }
}

Usage

Importing Reports

Option 1: With Existing Asset

If you already have an asset created in Conviso Platform:

mutation {
  importMobsf(
    input: {
      file: $file
      asset_id: "123"
    }
  ) {
    controlSyncStatus {
      id
      status
    }
    errors
  }
}

Option 2: With Company ID (Auto-Create Asset)

If you want the system to find or create an asset based on the app name:

mutation {
  importMobsf(
    input: {
      file: $file
      company_id: "456"
    }
  ) {
    controlSyncStatus {
      id
      status
      asset {
        id
        name
      }
    }
    errors
  }
}

note

When using company_id without asset_id, ensure your MobSF report contains the app_name field. The system will:

• Search for an existing asset with that name in the company
• Create a new asset if none exists (requires asset creation permissions)

Report Structure

The MobSF JSON report should follow this structure:

{
  "app_name": "MyMobileApp",
  "package_name": "com.example.myapp",
  "version_name": "1.0.0",
  "version_code": "1",
  "file_name": "myapp.apk",
  "appsec": {
    "app_name": "MyMobileApp",
    "file_name": "myapp.apk",
    "hash": "abc123...",
    "version_name": "1.0.0",
    "package_name": "com.example.myapp",
    "security_score": 75,
    "high": [
      {
        "title": "Insecure Data Storage",
        "description": "The app stores sensitive data insecurely...",
        "section": "storage"
      }
    ],
    "warning": [
      {
        "title": "Weak Cryptography",
        "description": "The app uses weak cryptographic algorithms...",
        "section": "crypto"
      }
    ],
    "info": [],
    "secure": [],
    "hotspot": []
  },
  "sbom": {
    "components": [
      {
        "name": "library-name",
        "version": "1.2.3"
      }
    ]
  }
}

Severity Buckets

MobSF organizes findings into severity buckets:

• high: Critical security issues requiring immediate attention
• warning: Security concerns that should be addressed
• info: Informational findings
• secure: Secure practices detected
• hotspot: Security hotspots identified

The integration automatically maps these to Conviso Platform severity levels.

SBOM Import

If your MobSF report contains SBOM (Software Bill of Materials) data in the sbom field, it will be automatically imported using the Sbom::ImporterService. The SBOM import runs before the security findings import.

API Endpoints

The integration provides the following GraphQL mutation:

GraphQL Mutation: importMobsf

Arguments

• file (required): The MobSF JSON report file (Upload type)
• asset_id (optional): ID of an existing asset to associate the report with
• company_id (optional): ID of the company/scope. Required if asset_id is not provided

Response Fields

• controlSyncStatus: Status tracking object with the following fields:
  • id: Status record ID
  • status: Current status (pending, succeeded, failed)
  • externalVulnerabilityCount: Total findings in the report
  • importedVulnerabilityCount: Successfully imported findings
  • createdVulnerabilityCount: New findings created
  • successCount: Number of successful imports
  • failureCount: Number of failed imports
  • failureReason: Error message if status is failed
  • estimatedDurationInSeconds: Processing duration
• errors: Array of error messages (empty if successful)

Error Types

• AssetNotFoundError: Asset not found or doesn't belong to the company
• AppNameRequiredError: app_name is required when using company_id without asset_id
• InvalidInputError: Invalid input parameters or JSON format

Examples

cURL Example

curl -X POST https://api.convisoappsec.com/graphql \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: multipart/form-data" \
  -F "operations={\"query\":\"mutation($file: Upload!) { importMobsf(input: {file: $file, company_id: \\\"123\\\"}) { controlSyncStatus { id status } errors } }\",\"variables\":{\"file\":null}}" \
  -F "map={\"0\":[\"variables.file\"]}" \
  -F "0=@mobsf_report.json"

JavaScript/TypeScript Example

import { gql } from '@apollo/client';

const IMPORT_MOBSF = gql`
  mutation ImportMobsf($file: Upload!, $companyId: ID) {
    importMobsf(
      input: {
        file: $file
        company_id: $companyId
      }
    ) {
      controlSyncStatus {
        id
        status
        asset {
          id
          name
        }
      }
      errors
    }
  }
`;

// Usage with Apollo Client
const [importMobsf] = useMutation(IMPORT_MOBSF);

const handleImport = async (file, companyId) => {
  try {
    const result = await importMobsf({
      variables: {
        file,
        companyId
      }
    });
    
    console.log('Status:', result.data.importMobsf.controlSyncStatus);
  } catch (error) {
    console.error('Import failed:', error);
  }
};

Troubleshooting

Common Issues

"You need to provide the asset_id or company_id"

Solution: Provide at least one of asset_id or company_id in the mutation input.

"App name is required when company_id is provided without asset_id"

Solution: Ensure your MobSF JSON report contains the app_name field at the root level or within the appsec object.

"User does not have access to this asset"

Solution: Verify that:

• The user has proper permissions to access the asset
• The asset belongs to the specified company
• The user has the necessary role/permissions in Conviso Platform

"Invalid JSON file"

Solution: Ensure your MobSF report is valid JSON. Validate it using a JSON validator before importing.

"Asset not found"

Solution:

• Verify the asset_id is correct
• If using company_id only, ensure the app_name in the report matches an existing asset name, or ensure you have permissions to create new assets

Status Monitoring

Monitor the import progress by querying the import status:

query {
  controlSyncStatus(id: "status_id") {
    status
    externalVulnerabilityCount
    importedVulnerabilityCount
    createdVulnerabilityCount
    failureCount
    failureReason
  }
}

Status values:

• pending: Import is being processed
• succeeded: Import completed successfully
• failed: Import failed (check failureReason for details)

Best Practices

1. Validate JSON Before Import: Always validate your MobSF JSON report before importing to catch format errors early
2. Monitor Import Status: Use the returned controlSyncStatus ID to monitor the import progress
3. Handle Errors Gracefully: Check the errors array in the response and handle errors appropriately
4. Use Asset IDs When Possible: If you know the asset ID, use it directly for faster processing
5. Batch Processing: For multiple reports, process them sequentially and monitor each import status
6. SBOM Data: Include SBOM data in your MobSF reports when available for comprehensive component tracking

Support

If you have any questions or need help using the MobSF integration, please don't hesitate to contact our support team.