To facilitate a transparent user experience and to enable full third-party integration with ObjectSecurity’s BinLens™ (formerly ObjectSecurity OT.AI Platform), OpenAPI Initiative functionality is natively integrated into the platform.
The “OpenAPI Page” details the API routes for interacting with BinLens. The API routes, corresponding description, and ‘Send” button are all listed on the left panel. Clicking the “Send” button queries the route, producing output on the right panel. Additionally, you may toggle between different API routes via a dropdown menu:
Additionally, some API routes require additional parameters or arguments. These parameters and arguments are listed on the left panel if needed:
External Usage
Our API may also be queried externally from any network connection with access to your deployment. Depending on your deployment type, the URL used to query the routes will differ.
Offline/On-Prem Virtual Machine:
Typically, an Offline/On-Prem virtual machine will be accessible via localhost. In this case, the following URL format will suffice:
https://localhost/rbui/
If your On-Prem virtual machine is hosted on a private network, the following URL format will suffice, with ip_address referring to the IP address of your deployment on your local network.
https:///rbui/
(The
Cloud Deployment:
For Cloud Deployments, the API will be accessible from anywhere on the Internet. The following URL will be used, with deployment_name referring to the name of your cloud deployment.
https://.objectsecurity.io/rbui/
(The
Note on bearer token:
Most BinLens API routes require a Bearer authentication token. You can learn to get this Bearer token under Authentication in the Available Routes section.
You can read more about Bearer tokens here.
Available Routes
This section provides a general overview of the purpose and output of each route. Information regarding the specific parameters and exact output schema can be found in the application itself.
General:
General routes handle the most basic usage of BinLens, mainly including fetching data to view.
- GET /assessor/getassets
You can use this route to get a list of your assets. Assets have a set of binaries that have each been analyzed.
- POST /assessor/getbinaries
Use this route to get the set of analyzed binaries in a given asset.
- POST /assessor/getresults
Use this route to get analysis results for a given binary.
- POST /assessor/getcwe
Get additional information on specific CWEs.
Assessments & Analysis:
These routes handle the analysis process, including the ability to queue up and start various assessments.
- GET /assessor/getassetprogress
Gets the current analysis progress of all ongoing analyses in the user’s current organization.
- GET /assessor/listbinaries
Gets the set of binaries uploaded to the dropzone.
- POST /saas/addfile
Uploads a binary to the dropzone.
- POST /saas/rmfile
Removes a binary from the dropzone.
- POST /saas/start
Starts the analysis procedure on the binaries in the dropzone.
Asset Management:
These routes handle the managing of assets after they have been analyzed. Various actions can be taken on assets, including deleting or updating multiple asset fields.
- GET /assessor/getnumnew
Gets the number of new assets in an organization. New assets are those that haven’t been viewed yet after being analyzed.
- POST /assessor/deleteasset
Deletes an asset from an organization.
- POST /assessor/renameasset
Renames an asset.
- POST /assessor/update/assetdescription
Updates an asset’s description.
- POST /assessor/updateassettype
Updates an asset’s type.
- POST /assessor/markassetviewed
Marks an asset as viewed.
- GET /saas/asset/{assetid}/audit
Gets the audit log for an asset.
Facility Management:
These routes handle the management of facilities. Facilities each have a location and set of child assets located within the facility.
- GET /assessor/getfacilities
Gets all the facilities in the organization.
- POST /assessor/createfacility
Creates a new facility.
- POST /assessor/updatefacility
Updates an existing facility.
- GET /assessor/getassetsinfacility/{facility_id}
Get the assets in a facility.
- GET /assessor/deletefacility/{facility_id}
Deletes a facility.
- GET /assessor/getdefaultfacility
Each organization has a default facility that cannot be deleted. All assets in an organization are analyzed in this default facility by default.
Authentication:
Authentication routes manage user login, role-based querying, and 2FA.
- POST /saas/mfalogin
Gets an “access_token” that may be set as the Bearer Token when calling the “/saas/validate_totp” route. This route acts as the first factor of 2-factor authentication. “/saas/validate_totp” acts as the second factor.
- GET /saas/generate_totp
Generates a time-based one-time password for the current user. This TOTP can be converted into a QR code and scanned with Google Authenticator for 2 Factor Authentication.
- POST /saas/validate_totp
Validates a user’s time-based one-time password and returns to them a token that may be set as the Bearer Token when accessing all other routes of the API. This route acts as the second factor of 2-factor authentication, with “/saas/mfalogin” being the first.
- POST /saas/auth/user/add
Creates a new user.
- POST /saas/auth/password
Updates a user’s password.
- GET /saas/auth/userinvite/user/{user_id}
Invites a user to the server. Returns a token specific to the “user_id” set in the API route. The token may be redeemed by the user using the “/saas/auth/userinvite/redeem/{invite}” route.
- GET /saas/auth/userinvite/redeem/{invite}
Redeems an invite generated using the “/auth/userinvite/user/{user_id}” route. Returns a token that may be used to set up a new account.
- POST /saas/auth/user/eula/accept
Accepts the EULA for the calling user.
- GET /saas/auth/user/{userid}/profile
Gets a user’s profile.
Organization Management:
These routes handle the managing of organizations. Organizations each have a set of child facilities and a set of child users. Organizations may have multiple administrators. The server SUPERADMIN is a part of every organization, and there may only ever be one SUPERADMIN at a time.
- GET /assessor/getdashboard
Gets the data needed to generate the dashboard on the UI.
- GET /saas/auth/userall
Gets all the users in an organization.
- POST /saas/auth/user/addroles
Assigns a user new roles in an organization. This is equivalent to adding a user to an organization, should the user not already have roles in the organization.
- POST /saas/auth/user/removeroles
Remove roles from a user in an organization. This is equivalent to removing a user from an organization, should the user not have any remaining roles in the organization after this route has been called.
- POST /saas/auth/user/setorg
Swaps the org a user is currently viewing.
- POST /saas/auth/organization/add
Adds an organization.
- POST /saas/auth/organization/update
Updates an organization.
- GET /saas/org/audit
Gets the audit log of an organization. The audit log tracks the history of all analyzed assets in the organization.