From 9bcc3134ab20a2e0bc89a2eb58d4bf1102ced43b Mon Sep 17 00:00:00 2001 From: david Date: Tue, 25 Feb 2020 14:27:54 +0200 Subject: [PATCH 1/2] revs to README.md --- README.md | 62 +++++++++++++++++++++++++------------------------------ 1 file changed, 28 insertions(+), 34 deletions(-) diff --git a/README.md b/README.md index 08fe4cb..323ee58 100644 --- a/README.md +++ b/README.md @@ -1,47 +1,42 @@ # **Portshift Orb for CircleCi** -## **What is Portshift Orb?** -With this orb you can easily integrate Portshift identity creation and vulnerabilities scans into your CircleCI Workflows. -Portshift identity creation is essential part of Portshift runtime security, authenticating and authorizing containers build and deployments with vulnerabilities scan results. The scan engine is currently based on [Clair](https://github.com/quay/clair), in the future additional scan engines will be added to Portshift Orb to enhance the vulnerabilities information. -Portshift Orb is an easy way to get started with Portshift runtime security platform, the image identity and the vulnerabilities scan results will be shown in Portshift Management platform. +## **What is the Portshift Orb?** +The Portshift Orb enables you to you to scan images for vulnerabilities in CircleCI, and report results to the Portshift server. +With this orb you can easily integrate Portshift vulnerabilities scans into your CircleCI Workflows. -## **How to use Portshift Orb** +Portshift workload runtime security policies can use vulnerabilities scan results as a criteria for allow or blocking images from running in Portshift protected environments. -### **Prerequisites** -1. User-Account: Create a user account in portshift (note: Portshift is a s commercial software, so you'll need a license to create a user accouunt before using this orb Go to: [www.portshift.io](www.portshift.io). After receiving a "New User" onboarding email, go to Portshift's user-portal (www.console.portshift.io) to enter your domain. - -2. Define Service Account: In the user domain you need to define a new "service account": +The scan engine is based on [Clair](https://github.com/quay/clair), though additional scan engines may be added, to enhance the vulnerabilities information. -3. Go to System (upper tab "manage users") +Portshift Orb is an easy way to get started with Portshift runtime security platform. Image identity and the vulnerabilities scan results from your CI pipeline are sent to Portshift, where you can see them on the Management console. -4. Create new user with service user role - -     ![new user](Images/New%20user%20image.png) +## **How to use the Portshift Orb** -5. After creating a new service user select its "token" from the users table - -     ![new user token](Images/New%20user%20token.png) +### **Prerequisites** +1. Create a Portshift user account. Portshift is a commercial SaaS platform, so you'll need a license to create a user account, before you can use the orb (see [www.portshift.io](www.portshift.io)). When you receive the "New User" onboarding email, go to the Portshift user-portal (www.console.portshift.io) to enter your domain. +2. Once you have opened an account on Portshift, define a Service User account. -6. In the token page, copy the "Access Key" and ""Secret Key" (you can use the copy icon on their right side) + 1. Go to the *System* page, and select the *Manage Users* tab. + 1. Create a new user, with the Service User role. +     ![new user](Images/New%20user%20image.png) + 1. Click on the Token icon for the new user, in the *Users* page. +      ![new user token](Images/New%20user%20token.png) + 1. Copy the *Access Key* and *Secret Key* (use the copy icon).   -7. In CircleCI App go to "Organization Settings"-> Context ->Create new Context - -     ![context](Images/Context.jpg) - - - -8. Create 2 new environment variables for Portshift's "Access Key" and "Secret Key" +1. In CircleCI, navigate to Organization Settings> Context >Create new Context +      ![context](Images/Context.jpg) +1. Create two new CircleCI environment variables for the Portshift *Access Key* and *Secret Key*   -### **Adding Portshift Orb to your pipeline** +### **Add the Portshift Orb to your CircleCI pipeline** -Create a a directory where you will build your image. This will later be persisted to a [Workspace](https://circleci.com/docs/2.0/concepts/#workspaces-and-artifacts) +Create a a directory where you will build your image. This will later be persisted to a [Workspace](https://circleci.com/docs/2.0/concepts/#workspaces-and-artifacts). -`- run: mkdir -p workspace ` +```- run: mkdir -p workspace ``` -Build your image +Build your image: -`- run: docker build -t ` +```- run: docker build -t ``` Save the image to the workspace: @@ -52,11 +47,11 @@ Save the image to the workspace:               - image.tar ``` -Add Portshift Orb +Add the Portshift Orb: `portshiftscanner: 'portshift/portshift-scanner@1.0.0` -Create a new job for Portshift Orb +Create a new job for Portshift Orb: ``` jobs: @@ -73,11 +68,10 @@ jobs: ### **Orb Output** -In the job's output you can see the vulnerabilities scan results +You can see the scan results in the job output.     ![job output](Images/output.png) -    -In portshift management "images tab" you'll see a new record with your image identity,vulnerabilities scan results +The results are also sent to Portshift. View them in the *Images* tab of the *Workloads* page. You will see a new record with your image identity, and the vulnerabilities scan results. From 5950a4cec53e26efda6ca04db39ac9b576616307 Mon Sep 17 00:00:00 2001 From: david Date: Mon, 9 Mar 2020 10:56:36 +0200 Subject: [PATCH 2/2] revisions to README.md --- README.md | 152 +++++++++++++++++++++++++++--------------------------- 1 file changed, 75 insertions(+), 77 deletions(-) diff --git a/README.md b/README.md index 323ee58..18cd15a 100644 --- a/README.md +++ b/README.md @@ -1,77 +1,75 @@ -# **Portshift Orb for CircleCi** - -## **What is the Portshift Orb?** -The Portshift Orb enables you to you to scan images for vulnerabilities in CircleCI, and report results to the Portshift server. -With this orb you can easily integrate Portshift vulnerabilities scans into your CircleCI Workflows. - -Portshift workload runtime security policies can use vulnerabilities scan results as a criteria for allow or blocking images from running in Portshift protected environments. - -The scan engine is based on [Clair](https://github.com/quay/clair), though additional scan engines may be added, to enhance the vulnerabilities information. - -Portshift Orb is an easy way to get started with Portshift runtime security platform. Image identity and the vulnerabilities scan results from your CI pipeline are sent to Portshift, where you can see them on the Management console. - -## **How to use the Portshift Orb** - -### **Prerequisites** -1. Create a Portshift user account. Portshift is a commercial SaaS platform, so you'll need a license to create a user account, before you can use the orb (see [www.portshift.io](www.portshift.io)). When you receive the "New User" onboarding email, go to the Portshift user-portal (www.console.portshift.io) to enter your domain. - -2. Once you have opened an account on Portshift, define a Service User account. - - 1. Go to the *System* page, and select the *Manage Users* tab. - 1. Create a new user, with the Service User role. -     ![new user](Images/New%20user%20image.png) - 1. Click on the Token icon for the new user, in the *Users* page. -      ![new user token](Images/New%20user%20token.png) - 1. Copy the *Access Key* and *Secret Key* (use the copy icon). -  -1. In CircleCI, navigate to Organization Settings> Context >Create new Context -      ![context](Images/Context.jpg) -1. Create two new CircleCI environment variables for the Portshift *Access Key* and *Secret Key* -  -### **Add the Portshift Orb to your CircleCI pipeline** - -Create a a directory where you will build your image. This will later be persisted to a [Workspace](https://circleci.com/docs/2.0/concepts/#workspaces-and-artifacts). - -```- run: mkdir -p workspace ``` - -Build your image: - -```- run: docker build -t ``` - -Save the image to the workspace: - -``` - - persist_to_workspace: -          root: workspace -          paths: -              - image.tar -``` - -Add the Portshift Orb: - -`portshiftscanner: 'portshift/portshift-scanner@1.0.0` - -Create a new job for Portshift Orb: - -``` -jobs: -      - docker-build -      - portshiftscanner/scan-image: -          requires: -            - docker-build -          context: portshift-credentials -          image_name: -          image_tag: -          access_key: ${ACCESS_KEY} -          secret_key: ${SECRET_KEY} -``` - -### **Orb Output** - -You can see the scan results in the job output. -    - ![job output](Images/output.png) - -The results are also sent to Portshift. View them in the *Images* tab of the *Workloads* page. You will see a new record with your image identity, and the vulnerabilities scan results. - - +# **Portshift Orb for CircleCi** + +## **What is the Portshift Orb?** +The Portshift Orb enables you to you to scan images for vulnerabilities, in CircleCI, and report the results to the Portshift server. It can also generate the Portshift ID for an image, based on the image hash and image metadata. Portshift uses this ID to track workloads in protected environments. + +Portshift workload runtime security policies can use vulnerabilities scan results as a criteria for allow or blocking images from running in Portshift protected environments. + +The scan engine is based on [Clair](https://github.com/quay/clair), though additional scan engines may be added, to enhance the vulnerabilities information. + +Portshift Orb is an easy way to get started with Portshift runtime security platform. Image identity and the vulnerabilities scan results from your CI pipeline are sent to Portshift, where you can see them on the Management console. + +## **How to use the Portshift Orb** + +### **Prerequisites** +1. Create a Portshift user account. Portshift is a commercial SaaS platform, so you'll need a license to create a user account, before you can use the orb (see [www.portshift.io](www.portshift.io)). When you receive the "New User" onboarding email, go to the Portshift user-portal (www.console.portshift.io) to enter your domain. + +2. Once you have opened an account on Portshift, define a Service User account. + + 1. Go to the *System* page, and select the *Manage Users* tab. + 1. Create a new user, with the Service User role. +     ![new user](Images/New%20user%20image.png) + 1. Click on the Token icon for the new user, in the *Users* page. +      ![new user token](Images/New%20user%20token.png) + 1. Copy the *Access Key* and *Secret Key* (use the copy icon). +  +1. In CircleCI, navigate to Organization Settings> Context >Create new Context +      ![context](Images/Context.jpg) +1. Create two new CircleCI environment variables for the Portshift *Access Key* and *Secret Key* +  +### **Add the Portshift Orb to your CircleCI pipeline** + +Create a a directory where you will build your image. This will later be persisted to a [Workspace](https://circleci.com/docs/2.0/concepts/#workspaces-and-artifacts). + +```- run: mkdir -p workspace ``` + +Build your image: + +```- run: docker build -t ``` + + +``` + - persist_to_workspace: +          root: workspace +          paths: +              - image.tar +``` + +Add the Portshift Orb: + +`portshiftscanner: 'portshift/portshift-scanner@1.0.0` + +Create a new job for Portshift Orb: + +``` +jobs: +      - docker-build +      - portshiftscanner/scan-image: +          requires: +            - docker-build +          context: portshift-credentials +          image_name: +          image_tag: +          access_key: ${ACCESS_KEY} +          secret_key: ${SECRET_KEY} +``` + +### **Orb Output** + +You can see the scan results in the job output. +    + ![job output](Images/output.png) + +The results are also sent to Portshift. View them in the *Images* tab of the *Workloads* page. You will see a new record with your image identity, and the vulnerabilities scan results. + +