Add the ability to create and edit detailed policies and associated proprietary queries.

[noahtalerman]

Goals

As an admin or maintainer (global or team), I want to create a new policy with a proprietary query that is owned by the policy so that my policy query is distinct and separate from other queries.

Overview

As part of #2711, policies will now be distinct entities with their own name, description and proprietary queries. Policies will no longer be associated with general queries. We need to create the supporting UI by adding new "Create Policy" and "Edit Policy" flows.

Figma

Add the ability to create and edit detailed policies and associated proprietary queries: https://www.figma.com/file/hdALBDsrti77QuDNSzLdkx/?node-id=2897%3A73534

Tasks

1

• Add a new "New Policy" page at /policies/new
• User provides "Query" input.
• Default policy: SELECT 1 FROM osquery_info WHERE start_time > 1;
• User can click "Save policy" to open "Save Policy Modal"
• If a user clicks "Run" without saving, it will run the policy as a live query. This work is covered by Add ability to run live queries on new and existing policies #2713 and not included in this ticket.
• Ensure global and team observers cannot access this page.

---

2

• Create new "Save Policy Modal".
• User provides "Name" input.
• User provides "Description" input.
• User can click "Cancel" to close the modal without saving.
• User can click "Save" to save the new policy.

---

3

• Send HTTPS request to updated "Create Policy" endpoint.
• POST /api/v1/fleet/global/policies
• If team is selected, POST /api/v1/fleet/teams/{teamId}/policies
• On successful save, redirect user to new policy details page at /policies/{policyId}
• Update any other references to this endpoint in the codebase to avoid regression bugs.

Parameters:

• query - The SQL query that is used to create the policy’s query (required). query cannot be specified if query_id is - specified
• name - The name that is used to create the policy’s query (required)
• description - The description that is used to create the policy’s query
• query_id - query_id cannot be specified if query is specified

Request:

{
  “query”: “SELECT 1 FROM gatekeeper WHERE assessments_enabled = 1”,
  “name”: “Is Gatekeeper enabled on macOS devices?”,
  “description”: “Checks to make sure that the Gatekeeper feature is enabled on macOS devices. This feature enforces code signing and verifies downloaded applications before allowing them to run, thereby reducing the likelihood of inadvertently executing malware.”
}

Endpoint Description: Creates a new policy and associated proprietary query.

Response:

{
  "policy": {
      “query”: “SELECT 1 FROM gatekeeper WHERE assessments_enabled = 1”,
      "name": "Is Gatekeeper enabled on macOS devices?",
      “description”: “Checks to make sure that the Gatekeeper feature is enabled on macOS devices. This feature enforces code signing and verifies downloaded applications before allowing them to run, thereby reducing the likelihood of inadvertently executing malware.”
      "resolution": "Some resolution steps",
      "passing_host_count": 0,
      "failing_host_count": 0
    }
}

---

4

• Create new "Policy Details" page at /policies/{policyId}
• Layout is very similar to "Query Details" page.
• New edit icon. User can either select the text to edit, as currently handled on queries, or they can click on the edit icon. When in "editing" state, the pencil icon disappears.
• Allow user to edit policy name and include edit icon.
• Allow user to edit policy description and include edit icon.
• Allow user to edit policy query.
• User can click "Save" to save their changes.
• User can click "Run" to run the current policy as a live query. This work is covered by Add ability to run live queries on new and existing policies #2713 and not included in this ticket.
• On "Save" send request to new API endpoint endpoint (next item).
• Ensure global and team observers cannot access this page.

---

5

• Apply new edit pencil icon functionality to "Edit Query" page at /query/{queryId
• We want to ensure the same edit functionality is in place for both queries and policies.
• This item will be continued in Refine edit icon state for edit query and policy #3099

---

6

• Create interface for new policy endpoint that updates existing policy.
• PATCH /api/v1/fleet/policies/1
• • If team is selected, PATCH /api/v1/fleet/teams/{teamId}/policies

Endpoint Description: Modifies the policy and the query that the policy owns.

Parameters:

• query - the SQL query that is used to create the policy’s query
• name - the name that is used to create the policy’s query
• description - the description that is used to create the policy’s query
• resolution - the steps to resolve a policy

Request:

{
  “name”: “Is Gatekeeper enabled?”,
}

Response:

{
  "policy": {
      "id": 2,
      “query”: “SELECT 1 FROM gatekeeper WHERE assessments_enabled = 1”,
      "name": "Is Gatekeeper enabled?",
      “description”: “Checks to make sure that the Gatekeeper feature is enabled on macOS devices. This feature enforces code signing and verifies downloaded applications before allowing them to run, thereby reducing the likelihood of inadvertently executing malware.”
      “resolution”: "Some resolution steps",
      "passing_host_count": 0,
      "failing_host_count": 0
    }
}

---

7

• Update "Manage Policies" page to allow linking to policy details and removing a policy for maintainers and admins.
• Policy names listed in table should link to policy's details page.
• Replace "Remove" button with "Delete" button and associated delete icon.
• Global and team observers cannot click on the policy name, or delete it.

---

8

• Change "Remove Policy" modal title to "Delete Policy".
• Also update button from "Remove" to "Delete"
• Confirm deletion of a policy with a modal alert.

Backend notes

As can be assumed from the API changes, the idea behind this is to reflect the query, description, and any other policy attribute in the policies table directly, just like we do with labels.

As part of this work, we need to migrate away from the previous setup and copy the queries and so on into the new table.

Here's a longer conversation about this #2711

[noahtalerman]

@lukeheath do you have any concerns with the proposed changes to the Fleet UI?

Please note that these UI changes are dependent on changes to the /policies API routes. These changes to the API are still in discussion in the following issue: #2711

I think we'd be able to effectively estimate these frontend changes under the assumption that the API changes are complete. Please let me know if you disagree.

[lukeheath]

I think this ticket needs to be refined so the requirements are more explicit and less implicit. The goal is to create a checklist the developer can reference that itemizes every change necessary for this ticket to be considered complete. My hope is this will reduce the need of the developer to compare the app vs. Figma vs. goals to understand what they need to do. Ideally, a developer could reference only the ticket to understand the scope of work. What do you think of this?

Title:
Add the ability to create and edit detailed policies and associated proprietary queries.

Story:
As a global or team admin, I want to create a new policy with a proprietary query that is owned by the policy so that my policy query is distinct and separate from other queries.

Overview:
As part of #2711, policies will now be distinct entities with their own name, description and proprietary queries. Policies will no longer be associated with general queries. We need to create the supporting UI by adding new "Create Policy" and "Edit Policy" flows.

Figma:
https://www.figma.com/file/hdALBDsrti77QuDNSzLdkx/?node-id=2897%3A73534

Tasks:

• Add a new "New Policy" page at /policies/new
• User provides "Query" input.
• Default policy: SELECT 1 FROM osquery_info WHERE start_time > 1;
• User can click "Save policy" to open "Save Policy Modal"
• If a user clicks "Run" without saving, it will run the policy as a live query. This work is covered by Add ability to run live queries on new and existing policies #2713 and not included in this ticket.

• Create new "Save Policy Modal".
• User provides "Name" input.
• User provides "Description" input.
• User can click "Cancel" to close the modal without saving.
• User can click "Save" to save the new policy.

• Send HTTPS request to updated "Create Policy" endpoint.
• POST /api/v1/fleet/global/policies
• If team is selected, POST /api/v1/fleet/teams/{teamId}/policies
• On successful save, redirect user to new policy details page at /policies/{policyId}
• Update any other references to this endpoint in the codebase to avoid regression bugs.

Parameters:

• query - The SQL query that is used to create the policy’s query (required). query cannot be specified if query_id is - specified
• name - The name that is used to create the policy’s query (required)
• description - The description that is used to create the policy’s query
• query_id - query_id cannot be specified if query is specified

Request:

{
  “query”: “SELECT 1 FROM gatekeeper WHERE assessments_enabled = 1”,
  “name”: “Is Gatekeeper enabled on macOS devices?”,
  “description”: “Checks to make sure that the Gatekeeper feature is enabled on macOS devices. This feature enforces code signing and verifies downloaded applications before allowing them to run, thereby reducing the likelihood of inadvertently executing malware.”
}

Endpoint Description: Creates a new policy and associated proprietary query.

Response:

{
  "policy": {
      "query_id": 4,
      “query”: “SELECT 1 FROM gatekeeper WHERE assessments_enabled = 1”,
      "query_name": "Is Gatekeeper enabled on macOS devices?",
      “query_description”: “Checks to make sure that the Gatekeeper feature is enabled on macOS devices. This feature enforces code signing and verifies downloaded applications before allowing them to run, thereby reducing the likelihood of inadvertently executing malware.”
      "resolution": "Some resolution steps",
      "passing_host_count": 0,
      "failing_host_count": 0
    }
}

• Create new "Policy Details" page at /policies/{policyId}
• Layout is very similar to "Query Details" page.
• Allow user to edit policy name.
• Allow user to edit policy description.
• Allow user to edit policy query.
• User can click "Save" to save their changes.
• User can click "Run" to run the current policy as a live query. This work is covered by Add ability to run live queries on new and existing policies #2713 and not included in this ticket.
• On "Save" send request to new API endpoint endpoint (next item).

• Create interface for new policy endpoint that updates existing policy.
• PATCH /api/v1/fleet/policies/1
• • If team is selected, PATCH /api/v1/fleet/teams/{teamId}/policies

Endpoint Description: Modifies the policy and the query that the policy owns.

Parameters:

• query - the SQL query that is used to create the policy’s query
• name - the name that is used to create the policy’s query
• description - the description that is used to create the policy’s query
• resolution - the steps to resolve a policy

Request:

{
  “name”: “Is Gatekeeper enabled?”,
}

Response:

{
  "policy": {
      "id": 2,
      “query”: “SELECT 1 FROM gatekeeper WHERE assessments_enabled = 1”,
      "query_name": "Is Gatekeeper enabled?",
      “query_description”: “Checks to make sure that the Gatekeeper feature is enabled on macOS devices. This feature enforces code signing and verifies downloaded applications before allowing them to run, thereby reducing the likelihood of inadvertently executing malware.”
      “resolution”: "Some resolution steps",
      "passing_host_count": 0,
      "failing_host_count": 0
    }
}

• Update "Manage Policies" page to allow linking to policy details and removing a policy.
• Policy names listed in table should link to policy's details page.
• Replace "Remove" button with "Delete" button and associated delete icon.

• Change "Remove Policy" modal title to "Delete Policy".
• Confirm deletion of a policy with a modal alert.

• In the existing "Add Policy Modal", add a text link to create a new policy.

[lukeheath]

@noahtalerman There are a couple of areas where I'm asking for clarification in the checklist above. Please search for "CLARIFICATION" to find those.