README

A clean, fluent PHP wrapper for the Armis VIPR API, built for Laravel applications using Saloon.

Installation

Install the package via Composer:

composer require xternalsoft/lararmis-vipr

Publish the configuration file:

php artisan vendor:publish --tag="lararmis-vipr-config"

Configuration File (config/lararmis-vipr.php)

return [
    'base_url' => env('ARMIS_VIPR_BASE_URL', 'https://silkapi.us1.app.silk.security'),
    'client_id' => env('ARMIS_VIPR_CLIENT_ID'),
    'client_secret' => env('ARMIS_VIPR_CLIENT_SECRET'),
    'token' => env('ARMIS_VIPR_TOKEN'),
];

Authentication Flow

• If a pre-obtained JWT token is configured (ARMIS_VIPR_TOKEN), all requests will use it directly.
• If no token is provided but client_id and client_secret are set, the package will automatically make a login request to /api/v1/authenticate to retrieve and apply the token for subsequent requests.

Usage

Use the wrapper via the LararmisVipr Facade or via Dependency Injection.

🔐 Authentication

Manual Authentication

use Xternalsoft\LararmisVipr\Facades\LararmisVipr;

$response = LararmisVipr::auth()->authenticate('your_client_id', 'your_client_secret');
$token = $response->dto()->token;

Token Info

$info = LararmisVipr::auth()->tokenInfo();

🖥️ Assets

List Assets (Offset Pagination)

use Xternalsoft\LararmisVipr\Facades\LararmisVipr;

$response = LararmisVipr::assets()->list(page: 1, pageSize: 20);
$dto = $response->dto(); // Returns AssetListResponseData

List Assets (Cursor Pagination)

$response = LararmisVipr::assets()->listByCursor(cursor: 'MTcwMDY2NTQzMjE', pageSize: 15);
$dto = $response->dto(); // Returns AssetSearchResponseData

Get Asset by ID

$response = LararmisVipr::assets()->get('ast_01HBF3P2Y8K3M4J5N6P7Q8R9S0');
$asset = $response->dto(); // Returns AssetData

Search Assets with Filters

$filters = [
    [
        'field' => 'region',
        'value' => [
            ['operator' => 'equals', 'value' => 'us-east-1'],
        ]
    ]
];

$response = LararmisVipr::assets()->search(filters: $filters, pageSize: 10);
$dto = $response->dto(); // Returns AssetSearchResponseData

Get Field Attributes and Counts

$response = LararmisVipr::assets()->fields(fieldName: 'source', sortBy: 'count');

👥 Users

List Users

$response = LararmisVipr::users()->list(page: 1, pageSize: 10);
$dto = $response->dto(); // Returns UserListResponseData

Create User

$response = LararmisVipr::users()->create(
    emailAddress: 'john.doe@example.com',
    displayName: 'John Doe',
    permissions: 'admin'
);
$user = $response->dto(); // Returns UserData

Get User

$response = LararmisVipr::users()->get('john.doe@example.com');
$user = $response->dto(); // Returns UserData

Update User

$response = LararmisVipr::users()->update(
    emailAddress: 'john.doe@example.com',
    displayName: 'Jonathan Doe'
);

Delete User

$response = LararmisVipr::users()->delete('john.doe@example.com');

📊 Custom Reports

List Scheduled Reports

$reports = LararmisVipr::reports()->listScheduledCustomReports()->dto(); // Returns CustomReportData[]

List Report Executions

$runs = LararmisVipr::reports()->listCustomReportRuns('scheduled_report_id')->dto(); // Returns CustomReportRunData[]

Trigger Report Run

$run = LararmisVipr::reports()->executeCustomReportRun('scheduled_report_id')->dto(); // Returns CustomReportRunData

Get Report Run Status

$runStatus = LararmisVipr::reports()->getCustomReportRunStatus('report_id')->dto(); // Returns CustomReportRunData with downloadUrl

Get Latest Finished Run (Helper)

$latestRun = LararmisVipr::reports()->latestReadyRun('scheduled_report_id'); // Returns CustomReportRunData or null

⚙️ Background Jobs

Get Job Status

$response = LararmisVipr::jobs()->status('job_id');
$job = $response->dto(); // Returns JobStatusData

📦 File Helpers (Streaming & Parsing)

For large report exports (NDJSON or CSV), use these utilities to stream downloads and read compressed files line-by-line without running out of PHP memory.

1. Download Report File directly to disk

use Xternalsoft\LararmisVipr\Support\ReportDownloader;

$latestRun = LararmisVipr::reports()->latestReadyRun('scheduled_report_id');

$localPath = storage_path('app/reports/findings.json.gz');
ReportDownloader::download($latestRun, $localPath);

2. Stream Parse Gzipped NDJSON or CSV Files (LazyCollection)

use Xternalsoft\LararmisVipr\Support\ReportReader;

// Read NDJSON (.json.gz)
$records = ReportReader::streamNdjsonGz(storage_path('app/reports/findings.json.gz'));

// Read CSV (.csv.gz)
// $records = ReportReader::streamCsvGz(storage_path('app/reports/findings.csv.gz'));

// Process records sequentially using low memory
$records
    ->chunk(500)
    ->each(function ($chunk) {
        DB::table('findings')->insert($chunk->toArray());
    });

Testing

Run package tests using Pest:

composer test

License

The MIT License (MIT). See License File for details.