Create and Analyze a Project via the API

Updated on 02 Dec 2021
6 Minutes to read

Print
Dark
Light
PDF

Article summary

Did you find this summary helpful?

Thank you for your feedback

In Ion Channel, virtually any action performed in the UI can also be accomplished through the API. The steps below will walk you through this process of creating a project, analyzing the project, and obtaining the results of the analysis of the Ion Connect repository.

Getting Started

To start, you will need your Team ID and an API token.

You can find information on obtaining your Team ID here.
You can find information on generating an API token here.

In all of the following API command examples, you will replace TOKEN with your API token and TEAM_ID with your team ID.

Step 1: Create a Project

Here we are going to create a Git project with the minimum required information. For more information on all of the data provided when creating a new project via the API, see the Create Project Endpoint documentation.

At a minimum, creating a project requires that you provide the Team ID, Ruleset ID, project name, project type, source, and the branch in the case of a Git project. The description field must be present but can be empty.

Team ID - The ID of the team where the project will be created. See here for information on how to find the Team ID.
Ruleset ID - The ID of the ruleset to be applied to the project. In this case, we are using the default ruleset, which will already exist in your team. Information on how to get the ID of a ruleset can be found here.
Name - The name of the project. This can be anything that helps you identify the project.
Type - The type of project. Since we want to analyze the Ion Connect GitHub repository, we are using "git" here.
Source - Where to get the repository. Since this is JSON, we are escaping the slashes with backslashes.
Branch - This is only required for Git projects. In this case, we are going to use the master branch.
Description - We're leaving it blank, but you can put whatever you want here to provide future you or someone else some information on this project.
Active - This field is not required, but leaving it out would create the project in an archived state, which would prevent us from analyzing it in the next step.

Using the v1/project/createProject endpoint, the POST request will look something like this:

curl -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer TOKEN" \
-d '{
  "team_id": "TEAM_ID",
  "ruleset_id": "effe0a9c-2d60-4c5b-9098-98d198295138",
  "name": "Ion Connect",
  "type": "git",
  "source": "https:\/\/github.com/ion-channel\/ion-connect.git",
  "branch": "master",
  "description": "",
  "active": "true"
}' \
https://api.ionchannel.io/v1/project/createProject

After you run this (assuming you entered a valid API token and Team ID), you should see a response similar to this, but it will all be jumbled together on a single line.

The raw JSON output can be pretty hard to read. I use jq to clean it up at the command line. With that tool, you can simply add "| jq ." to the end of any API request to get the output in formatted JSON.

There are also many other tools to format the JSON to make it more readable. A search for JSON formatter should find you something.

{
  "data": {
    "id": "PROJECT_ID",
    "team_id": "TEAM_ID",
    "ruleset_id": "effe0a9c-2d60-4c5b-9098-98d198295138",
    "name": "Ion Connect",
    "type": "git",
    "source": "https://github.com/ion-channel/ion-connect.git",
    "branch": "master",
    "description": "",
    "active": true,
    "chat_channel": "",
    "created_at": "2021-10-26T23:10:32.938786Z",
    "updated_at": "2021-10-26T23:10:32.938786Z",
    "deploy_key": "",
    "should_monitor": false,
    "monitor_frequency": "",
    "poc_name": "",
    "poc_email": "",
    "username": "",
    "password": "",
    "key_fingerprint": "",
    "private": false,
    "aliases": [],
    "tags": [],
    "ruleset_history": null
  },
  "meta": {
    "total_count": 0,
    "offset": 0
  }
}

The piece of information you will need from this output is the value in the id field (c99fb7fd-dbb8-4fed-a6ad-b169c1eff43a in this case). This is the project ID of our new project, which we will use wherever PROJECT_ID is mentioned below.

Step 2: Analyze the Project

Now that we have created our new project, it is time to run an analysis. For this, we will utilize the v1/scanner/analyzeProject endpoint, the Project ID, the same Team ID, and your API token.

curl -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer TOKEN" \
-d '{
     "team_id":"TEAM_ID",
     "project_id":"PROJECT_ID"
}' \
https://api.ionchannel.io/v1/scanner/analyzeProject

This request should result in output similar to the following.

{
  "data": {
    "id": "ANALYSIS_ID",
    "team_id": "TEAM_ID",
    "project_id": "PROJECT_ID",
    "message": "Request for analysis ANALYSIS_ID on Ion Connect has been queued.",
    "branch": "master",
    "status": "queued",
    "unreachable_error": false,
    "analysis_event_src": "",
    "created_at": "2021-10-27T00:03:28.772949Z",
    "updated_at": "2021-10-27T00:03:28.772949Z",
    "scan_status": null,
    "deliveries": null,
    "ForCukes": false
  },
  "meta": {
    "total_count": 0,
    "offset": 0
  }
}

From this, the new piece of data that you want is the id. This is the ID of the analysis that we will use to get the analysis results.

Step 3: Get the Analysis Status and Summary

Now that we have initiated an analysis, we can get the status of the analysis and some high-level information about the scan results. For this, we will use the v1/scanner/getAnalysisStatus endpoint using the Analysis ID (id) from the previous step and the same Project and Team IDs.

curl -H "Authorization: Bearer TOKEN" \
https://api.ionchannel.io/v1/scanner/getAnalysisStatus?id=ANALYSIS_ID&team_id=TEAM_ID&project_id=PROJECT_ID

To determine whether the analysis has completed or not, look for the first "status" field. An analysis that has finished will have this field set to "finished." If the analysis has started but not yet completed, the value will be "analyzing." A completed analysis will show results similar to the following:

{
  "data": {
    "id": "abcd1234-ab12-ab12-ab12-abcde123456",
    "team_id": "bcde1234-ab12-ab12-ab12-abcde234567",
    "project_id": "cdef1234-ab12-ab12-ab12-abcde345678",
    "message": "Completed compliance analysis",
    "branch": "master",
    "status": "finished",
    "unreachable_error": false,
    "analysis_event_src": "",
    "created_at": "2021-10-28T18:45:14.467274Z",
    "updated_at": "2021-10-28T18:46:44.896402Z",
    "scan_status": [
      {
        "id": "abcd1234-34de-e53d-14e9-bcdef4567891",
        "analysis_status_id": "abcd1234-ab12-ab12-ab12-abcde123456",
        "project_id": "cdef1234-ab12-ab12-ab12-abcde345678",
        "team_id": "bcde1234-ab12-ab12-ab12-abcde234567",
        "message": "Finished community scan for Ion-Connect, community data was not detected.",
        "name": "community",
        "read": "false",
        "status": "finished",
        "created_at": "2021-10-28T18:45:34.175292Z",
        "updated_at": "2021-10-28T18:46:35.03248Z"
      },
      {
        "id": "abcd1234-8035-5b4c-2c4d-bcdef4567892",
        "analysis_status_id": "abcd1234-ab12-ab12-ab12-abcde123456",
        "project_id": "cdef1234-ab12-ab12-ab12-abcde345678",
        "team_id": "bcde1234-ab12-ab12-ab12-abcde234567",
        "message": "Finished vulnerability scan for Ion-Connect, found 0 vulnerabilities.",
        "name": "vulnerability",
        "read": "false",
        "status": "finished",
        "created_at": "2021-10-28T18:45:38.587231Z",
        "updated_at": "2021-10-28T18:45:41.726772Z"
      },
      {
        "id": "abcd1234-ab69-f726-be79-bcdef4567893",
        "analysis_status_id": "abcd1234-ab12-ab12-ab12-abcde123456",
        "project_id": "cdef1234-ab12-ab12-ab12-abcde345678",
        "team_id": "bcde1234-ab12-ab12-ab12-abcde234567",
        "message": "Finished ecosystems scan for Ion-Connect, Makefile, Go were detected in project.",
        "name": "ecosystems",
        "read": "false",
        "status": "finished",
        "created_at": "2021-10-28T18:45:36.564234Z",
        "updated_at": "2021-10-28T18:45:36.671205Z"
      },
      {
        "id": "abcd1234-8172-3996-aff3-bcdef4567894",
        "analysis_status_id": "abcd1234-ab12-ab12-ab12-abcde123456",
        "project_id": "cdef1234-ab12-ab12-ab12-abcde345678",
        "team_id": "bcde1234-ab12-ab12-ab12-abcde234567",
        "message": "Finished buildsystems scan for Ion-Connect, no compilers were detected in project.",
        "name": "buildsystems",
        "read": "false",
        "status": "finished",
        "created_at": "2021-10-28T18:45:32.133101Z",
        "updated_at": "2021-10-28T18:45:32.386468Z"
      },
      {
        "id": "abcd1234-a21a-6590-cd0d-bcdef4567895",
        "analysis_status_id": "abcd1234-ab12-ab12-ab12-abcde123456",
        "project_id": "cdef1234-ab12-ab12-ab12-abcde345678",
        "team_id": "bcde1234-ab12-ab12-ab12-abcde234567",
        "message": "Finished license scan for Ion-Connect, found Apache-2.0 license.",
        "name": "license",
        "read": "false",
        "status": "finished",
        "created_at": "2021-10-28T18:45:30.089214Z",
        "updated_at": "2021-10-28T18:45:30.430298Z"
      },
      {
        "id": "abcd1234-0548-f332-620d-bcdef4567896",
        "analysis_status_id": "abcd1234-ab12-ab12-ab12-abcde123456",
        "project_id": "cdef1234-ab12-ab12-ab12-abcde345678",
        "team_id": "bcde1234-ab12-ab12-ab12-abcde234567",
        "message": "Finished dependency scan for Ion-Connect, found 13 dependencies, 0 with no version and 0 with updates available.",
        "name": "dependency",
        "read": "false",
        "status": "finished",
        "created_at": "2021-10-28T18:45:28.061918Z",
        "updated_at": "2021-10-28T18:45:28.553256Z"
      },
      {
        "id": "abcd1234-95bc-08e5-216d-bcdef4567897",
        "analysis_status_id": "abcd1234-ab12-ab12-ab12-abcde123456",
        "project_id": "cdef1234-ab12-ab12-ab12-abcde345678",
        "team_id": "bcde1234-ab12-ab12-ab12-abcde234567",
        "message": "Finished clamav scan for Ion-Connect, found 0 infected files.",
        "name": "virus",
        "read": "false",
        "status": "finished",
        "created_at": "2021-10-28T18:45:26.136623Z",
        "updated_at": "2021-10-28T18:45:26.880093Z"
      },
      {
        "id": "abcd1234-3429-b53a-50a8-bcdef4567898",
        "analysis_status_id": "abcd1234-ab12-ab12-ab12-abcde123456",
        "project_id": "cdef1234-ab12-ab12-ab12-abcde345678",
        "team_id": "bcde1234-ab12-ab12-ab12-abcde234567",
        "message": "Finished difference scan for Ion-Connect, a difference was not detected.",
        "name": "difference",
        "read": "false",
        "status": "finished",
        "created_at": "2021-10-28T18:45:23.974696Z",
        "updated_at": "2021-10-28T18:45:24.690543Z"
      },
      {
        "id": "abcd1234-91e2-ca5b-da3b-bcdef4567899",
        "analysis_status_id": "abcd1234-ab12-ab12-ab12-abcde123456",
        "project_id": "cdef1234-ab12-ab12-ab12-abcde345678",
        "team_id": "bcde1234-ab12-ab12-ab12-abcde234567",
        "message": "Finished about_yml scan for Ion-Connect, valid .about.yml found.",
        "name": "about_yml",
        "read": "false",
        "status": "finished",
        "created_at": "2021-10-28T18:45:21.934351Z",
        "updated_at": "2021-10-28T18:45:22.052832Z"
      }
    ],
    "deliveries": {},
    "ForCukes": false
  },
  "meta": {
    "total_count": 0,
    "offset": 0
  }
}

Step 4: Get the Full Analysis Report

Once an analysis has finished, you can obtain the full analysis report with the v1/animal/getAnalysis endpoint. The output of a complete analysis report can be very large. Therefore, in this example, we will output the report to a file.

If you receive the message "Analysis not found," the cause may be that the analysis has not yet finished. You can use the getAnalysisStatus endpoint mentioned above to determine whether the analysis has finished or not.

curl -H "Authorization: Bearer TOKEN" \
https://api.ionchannel.io/v1/report/getAnalysis?analysis_id=ANALYSIS_ID&team_id=TEAM_ID&project_id=PROJECT_ID \
>> analysis_report.json

You can see an example of the output from this endpoint in the getAnalysis endpoint documentation.

Was this article helpful?

What's Next

Check for Vulnerabilities via the API

Table of contents