This section of the user guide describes how you can programmatically interact with the MetaDefender Storage Security REST API. Below are some common tasks that can be done using the available REST APIs:
- Authenticate to obtain a JSON Web Token(JWT)
- Start or stop a process(scan)
- Add / remove storage units
About this REST API
The exposed endpoint is located by default at http(s)://md-storage-server/api/ (for example, the authentication endpoint is available at http(s)://md-storage-server/api/user/authenticate). All requests are handled by the NGINX web server before being proxied to the backend API Gateway service.
All endpoints perform authentication and authorization checks. For these checks to succeed, a valid token should be presented in the Authorization header in the form of Bearer
Please note that all issued tokens have a timestamp and signature associated in order to prevent long-term usage without re - authentication.The lifespan of the token is currently set to 60 minutes, meaning you will have to request a new token before it expires in order to avoid error responses.
Useful links
Account
Manage your accounts
Fetch all accounts
Add an account
Update an account
Fetch account by ID
Delete an account
Fetch the number of accounts
Audit
List audit information
Fetch audit logs
Configuration
Import or export configuration file
Export configuration file
Import configuration file
Get enabled modules
Deep Cdr
Manage sanitized files
Revert encrypted file
External Logger
Manage external loggers
Retrieve external loggers
Update external logger state
Update a Syslog server configuration
Add a new Syslog server configuration
Delete external logger
File
Retrieve processed files information
Scan a file on demand
This request is used to update a scanned file with passwords, in case it is an encrypted archive andit could not be scanned because the passwords to decrypt it were not provided. It can also be used withoutproviding any passwords to simply rescan a specific file from a finished scan.
Fetch processing results for a file
File processing is done asynchronously and each analysis request is tracked by a file ID. Because processing a file is a potentially time-consuming operation, scheduling a file for processing and retrieving the results needs to be done using two separate API calls.
This request needs to be made multiple times until the analysis is complete. Analysis completion can be tracked using the processingState and the progress values from the response..
Enumerate processed files
Group
Manage your groups
Fetch all groups
Add a group
Update a group
Fetch group by ID
Delete a group
Fetch the number of groups
Health Status
API that responds with 200 OK if application is running.
Get health status
Opswat Central Management
Manage OPSWAT Central Management integration
Get OCM configuration
Enroll to OCM
UnEnroll to OCM
Get managed status
Check if MDSS is managed by OCM. This is called by OCM v7.
Set managed status
Notify that MDSS is managed. This is called by OCM v7.
Delete managed status
Remove MDSS from being managed. This is called by OCM v7.
Onboarding
Manage onboarding
Fetch onboarding configuration
Finish onboarding
Accept Eula
Report
Generate reports
Get scans report
Scan Configuration
List, add, update and delete Scan Configurations
Get Scan Configurations
Add a new Scan Configuration
Update an existing Scan Configuration
Get Scan Configuration by ID
Delete a Scan Configuration
Set a Scan Configuration as default
Get scan by ID
Get scan by ID with information regarding the previous and next scan
Start a scan
To scan a specific folder using the optional Folder parameter, provide the folder's name if you're using Box, OneDrive, or SharePoint integrations. For other storage integrations, you should provide the absolute path to the folder you want to scan.
Stop a scan
Get next scheduled scan
Delete scans
Scan Instance
List, add, update and delete Scan Instances
Get Scan Instances
Update an existing Scan Instance
Add a new Scan Instance
Get Scan Instance by ID
Delete a Scan Instance
Test
Scan Pool
List, add, update and delete Scan Pools
Get Scan Pools
Update an existing Scan Pool
Add a new Scan Pool
Get Scan Pool by ID
Delete a Scan Pool
Scan Workflow Snapshot
List scan workflow snapshots
Get all scan workflow snapshots by scan ID
Fetch storage security checklist
Fetch security checklist details
Update security checklist item
Verify the security checklist for storage
Enable/Disable the security checklist
Enable all security checklist items
Settings
List or update your settings
Get notifications configuration
Update notifications configuration
Fetch SMTP configuration
Update SMTP configuration
Online license activation
Offline license activation
Get license details
Deactivate license
Fetch retention configuration
Update retention configuration
Sso
Sso Authentication and Sso configuration update
Get Sso Configuration
Update Sso Configuration
Storage
Manage your storages
Fetch all storages
Fetch storage by ID
Delete a storage
Update a storage
Note! The following are templates for what is expected in the Credentials, CredentialsFile and Source fields. Please provide the correct values for your storage integration instead of null/false
Alibaba Cloud storage units:
Credentials: "{"Endpoint":null,"AccessKeyId":null,"AccessKeySecret":null,"UseRamRole":false}"
Source: "{"BucketName":null,"FolderLocation":null}"
Amazon S3 / S3 Compatible storage units:
Credentials: "{"ServiceUrl":null,"AccessKeyId":null,"SecretAccessKey":null,"RegionEndpoint":null,"AssumeRoleArn":null,"UseIamRole":false}"
Source: "{"BucketName":null,"FolderLocation":null}"
Azure Blob storage units:
Credentials: "{"TenantId":null,"ClientId":null,"ClientSecret":null,"StorageAccount":null}"
Source: "{"Container":null}"
Azure Files storage units:
Credentials: "{"AccountName":null,"AccountKey":null,"ShareName":null}"
Source: "{"FolderLocation":null}"
Box storage units:
CredentialsFile: upload the credentials file
Source: "{"FolderLocation":null}"
Dell Isilon / SMB Compatible storage units:
Credentials: "{"User":null,"Password":null,"Server":null}"
Source: "{"SharePath":null}"
Google Cloud storage units:
CredentialsFile: upload the credentials file
Credentials: "{"UseAdc":false}"
Source: "{"BucketName":null,"FolderLocation":null}"
OneDrive storage units:
Credentials: "{"TenantId":null,"ClientId":null,"ClientSecret":null}"
Source: "{"Group":null}"
Fetch storage users
Add a storage
Note! The following are templates for what is expected in the Credentials, CredentialsFile and Source fields. Please provide the correct values for your storage integration instead of null/false
Alibaba Cloud storage units:
Credentials: "{"Endpoint":null,"AccessKeyId":null,"AccessKeySecret":null,"UseRamRole":false}"
Source: "{"BucketName":null,"FolderLocation":null}"
Amazon S3 / S3 Compatible storage units:
Credentials: "{"ServiceUrl":null,"AccessKeyId":null,"SecretAccessKey":null,"RegionEndpoint":null,"AssumeRoleArn":null,"UseIamRole":false}"
Source: "{"BucketName":null,"FolderLocation":null}"
Azure Blob storage units:
Credentials: "{"TenantId":null,"ClientId":null,"ClientSecret":null,"StorageAccount":null}"
Source: "{"Container":null}"
Azure Files storage units:
Credentials: "{"AccountName":null,"AccountKey":null,"ShareName":null}"
Source: "{"FolderLocation":null}"
Box storage units:
CredentialsFile: upload the credentials file
Source: "{"FolderLocation":null}"
Dell Isilon / SMB Compatible storage units:
Credentials: "{"User":null,"Password":null,"Server":null}"
Source: "{"SharePath":null}"
Google Cloud storage units:
CredentialsFile: upload the credentials file
Credentials: "{"UseAdc":false}"
Source: "{"BucketName":null,"FolderLocation":null}"
OneDrive storage units:
Credentials: "{"TenantId":null,"ClientId":null,"ClientSecret":null}"
Source: "{"Group":null}"
Update scan configuration
Add a scan schedule
Update a scan schedule
Fetch scan schedules
Delete scan schedules
Retrieve storage user name
User
Create, list and update user accounts
Fetch active users
Register a user
Create a user
Authenticate with a username and password
Authenticate with a username and password to obtain a JWT token,Most of the APIs require authentication in the form of providing a JWT token. Call this API in order to receive a token but please note that it's only valid for an hour so it should be periodically refreshed.
Refresh user token
Logout
Update user role
Fetch users
Delete a user
Update a user
Request password reset
Reset user password
Object event trigger of real time processing
This endpoint takes the parameters and tries to find the file in the specified storage and applies the scan configuration for the specified file