feat: member improvements (#281)

docs/README.md

@@ -10,6 +10,6 @@ Users can search, browse objects, view a graph representation and review activit
 
 ## Deployment Specific Information
 
-If this documentation refers to things as 'deployment specific' then you should refer to your team's own documentation. Your deployment should show a link to your documentation on the homepage.
+If this documentation refers to things as 'deployment specific' then you should refer to your own documentation. Your deployment should show a link to your documentation on the homepage.
 
 This documentation is generic to all NR Broker installations.

docs/dev_account_token.md

@@ -1,22 +1,23 @@
 # Broker Account Token
 
-If you are assigned as a lead developer to a team that has a Broker Account then you are able to generate tokens for that Account.
-The information in the token is in the clear and can be read using tools like jwt.io.
+If you are assigned as a lead-developer to a team that has a Broker Account then you are able to generate tokens for that Account.
 
 See: [Broker JWT](/operations_jwt.md)
 
 ## How to generate a Token
 
 * Access NR Broker
-* Click on the Teams section. By default, only your teams are shown.
-* Click the row to open your team page.
+* Navigate to the browser and view the 'Team' collection
+* Find your team and navigate to it by clicking on the row
 * Find the 'Broker Account' section and the account you want to generate the token for. The token expiry (if one has been created) will be shown. Click the 'Generate' button to open the generate/renew token dialog.
 * Read the instructions and click 'Generate' button.
 
 Teams are encouraged to document the client_id used by a service. This documentation should clearly state the locations the account is stored. The `reason` field in intentions should be descriptive enough your team understands where it is opened from.
 
 Generated tokens are saved in vault 'tools' space for all associated services by default. This can occur even if Vault has not been enabled for a service.
 
+The information in the token is in the clear and can be read using tools like [jwt.io](https://jwt.io).
+
 ## Update Github Secrets
 
 ### Prerequisites
@@ -29,15 +30,25 @@ Generated tokens are saved in vault 'tools' space for all associated services by
 
 ### Renewing a token
 
-Tokens can be regenerated at anytime. The procedure is identical to generating a token. The previous token will continue working for an hour (if it is not already expired).
+Tokens can be regenerated at anytime. The procedure is identical to generating a token. The previous token will continue working for an hour (if it is not already expired). Only two tokens are ever active at any time.
+
+### Revoke a token
+
+If you need to revoke the current token immediately, generate the token twice. If you generate the token twice then the initial token's grace period of an hour ends. You can ignore the first generated token as it is only used to cancel the grace period.
 
 ## How to Lookup an Account from a Token
 
-If you are renewing a token for an account you are not familiar with then you may not know which account associated with it. The account can be looked up by:
+If you are renewing a token for an account you are not familiar with then you may not know which account associated with it. The account can be looked up by searching for the client_id in NR Broker.
+
+The client_id can be found in the following places:
+
+* In the key used to save the token to the Vault tools space
+* In the token's payload data by using a tool like [jwt.io](https://jwt.io)
+
+Once you have the client_id, you can find the account by:
 
-* Copy the existing token† and view the token payload by using a tool like jwt.io.
 * Copy the client_id claim value
 * Paste into the search in NR Broker
-* Click the search result. The expiry date in broker and the token can also be compared to ensure you are updating the correct location.
+* Click the search result. The expiry date and JTI in broker and the token can also be compared to ensure you are updating the correct token.
 
-† If you do not have access to view the token (GitHub secret?) then hope the client_id was documented somewhere.
+The client_id used by your service should be documented.

docs/operations_audit.md

@@ -1,8 +1,6 @@
 # Understanding the Audit Log
 
-NR Broker outputs both audit and access log streams to a configurable HTTP endpoint. How to receive, save and make the data searchable is outside the scope of the NR Broker documentation.
-
-It is recommended that your deployment forwards the logs to an OpenSearch deployment that also receives Vault's audit log and HTTP log as well. The logs from both NR Broker and Vault can then be examined together to give a fulsome view of activity.
+NR Broker outputs both audit and access log streams to a configurable HTTP endpoint and a rotated log file.
 
 ## Format
 
@@ -19,19 +17,32 @@ The `event.dataset` field can be used to determine the type of event.
 
 If you are looking for a specific type of audit event, you're going to be looking at the event.action field.
 
+See: https://www.elastic.co/guide/en/ecs/current/ecs-event.html#field-event-action
+
 | event.action | Description |
 | --- | --- |
-| intention-open | Initial event when an application opens. |
-| intention-close | Final event when an intention is closed. |
 | authentication | JWT authentication event (occurs before intention is opened) |
-| auth-database-access | Request for database access |
-| auth-package-installation | Request to install a package (software) onto a server |
-| auth-package-provision | Request to provision a secret id for an application |
-| auth-server-access | Request to access a server |
+| intention-close | Final event when an intention is closed. |
+| intention-open | Initial event when an application opens. |
+| package-approval |  |
+| process-end |  |
+| process-start |  |
+| sync-tools |  |
 | generate-secret-id | Generation of a secret id for an application |
-| generate-token | Generation of a token for an application |
+| token-generation | Generation of a token for an application |
 
-See: https://www.elastic.co/guide/en/ecs/current/ecs-event.html#field-event-action
+#### Actions
+
+All "*action*-" events also have an "*auth*-" counterpart that records success or failure authorizing an action when an intention is opened.
+
+| event.action | Description |
+| --- | --- |
+| *action*-backup | Backup of data. |
+| *action*-database-access | Accesses a database. |
+| *action*-server-access | Accesses a server. |
+| *action*-package-configure | Alters an installed package's configuration. |
+| *action*-package-installation | Installs a package (software) onto a server. |
+| *action*-package-provision | Provision a secret id for a service. Can also configure a package. |
 
 ### Audit Tracing Fields
 
@@ -41,7 +52,7 @@ See: https://www.elastic.co/guide/en/ecs/current/ecs-tracing.html
 
 ### Audit Auth Fields
 
-All auth fields are custom to the Broker audit log.
+All auth fields are custom to the Broker audit log. If you are using a strict Elastic Common Schema, these fields should be added.
 
 | Field | Mandatory | Type | Description | Values |
 | ----- | --------- | ---- | ----------- | ------ |
@@ -63,3 +74,13 @@ Once you find the unwrap audit document, the response field contains the hashed
 For a 'generate-token' action, find the field response.auth.accessor (or response.auth.client_token). This is the (hashed) token the client will be used to make requests to Vault. So, you can search for usages of that token auth.accessor (or: auth.client_token). If nothing is found, the token was never used.
 
 The Broker creation event (field: auth.client_token) can locate the Vault (field: auth.client_token) unwrap event  The Vault unwrap event (fields in response.auth.\*) can locate Vault usage events.
+
+## Searching and combining with other services
+
+This information is deployment specific. Your deployment should show a link to your documentation on the homepage.
+
+## Setting up an audit data ingestion pipeline
+
+How to receive, save and make the data searchable is outside the scope of the NR Broker documentation.
+
+It is recommended that your deployment forward NR Broker's logs to a search and observability suite like OpenSearch. Vault's audit log and HTTP log should be forward here as well. The logs from both NR Broker and Vault should be examined together to give a fulsome view of activity.

docs/ops_manage_team.md

@@ -1,32 +1,36 @@
-# Manage my Team
+# Manage my teams
 
-If you are assigned as a Team owner in NR Broker then group membership has been delegated to you.
+You can view teams in the Broker by navigating to the browse page (/browse) and selecting the team collection from the dropdown menu. To see only the teams of which you are a member, select  show "connected." For convenience, a direct link is available in the sections tab on the home page.
 
-All users can view your group and its membership.
+If you are assigned the owner role, membership management has been delegated to you. Owners can edit team membership by clicking the "Members" button in the top-right corner.
 
 ## How to add/remove users
 
-* Access the NR Broker
-* Click on the Teams section
-
-By default, only your teams are shown. Click the 'members' buttons.
-
+* Access NR Broker
+* Navigate to the browser and view the 'Team' collection
+* Find the team to modify and navigate to it by clicking on the row
+* Click the "Members" button
 * Modify role membership
 
-**To add:** Select the role in the drop-down. Type until the desired user is displayed and select. Click add.
+**To add:** Select the desired role from the dropdown menu. Type until the desired user appears, then select them and click "Add."
 
-> User not showing? Users are imported the first time they login to NR Broker. The easiest method to add users is to send them the link and have them login.
+> User not showing? Users are imported the first time they login to NR Broker. The easiest way to add users is to send them the link and have them login.
 
-**To remove:** Click the user to check them and then click remove for the role
+**To remove:** Click the user to select them and then click remove for the role
 
 ## What do the roles mean?
 
 | Role | Description |
 |--- | ---|
 | Owner | Can manage role members for this team |
-| Lead-developer | Extended access to this team's entities which includes the ability to generate Broker Tokens |
+| Lead-developer | Extended access to this team's entities, including the ability to generate Broker account tokens |
 | Developer | Base read/write access to this team's entities |
+| Tester | Limited access with ability to approve builds |
 
 ## How to reassign ownership
 
-Assign a new person as an owner of the team. This person can then remove you from the team.
+To assign a new person as the owner of the team, add the new person as an owner of the team. If required, this person can then remove you as an owner of the team.
+
+## Not a member of a team?
+
+Any user can view every team and its membership. If you wish to request access, please reach out to a team owner or use the team's contact details.