Skip to content

Commit d9b49c5

Browse files
paulOsinskiPaul OsinskiMaffoochhblankenship
authored
[docs] add Tags article (#12294)
* add tags article * Update docs/content/en/working_with_findings/organizing_engagements_tests/tagging_objects.md Co-authored-by: Cody Maffucci <46459665+Maffooch@users.noreply.github.com> * fix failing build * Update docs/content/en/working_with_findings/organizing_engagements_tests/tagging_objects.md Co-authored-by: Harold Blankenship <36673698+hblankenship@users.noreply.github.com> * Update docs/content/en/working_with_findings/organizing_engagements_tests/tagging_objects.md Co-authored-by: Harold Blankenship <36673698+hblankenship@users.noreply.github.com> * Update docs/content/en/working_with_findings/organizing_engagements_tests/tagging_objects.md Co-authored-by: Harold Blankenship <36673698+hblankenship@users.noreply.github.com> * Update docs/content/en/working_with_findings/organizing_engagements_tests/tagging_objects.md Co-authored-by: Harold Blankenship <36673698+hblankenship@users.noreply.github.com> * Update docs/content/en/working_with_findings/organizing_engagements_tests/tagging_objects.md Co-authored-by: Harold Blankenship <36673698+hblankenship@users.noreply.github.com> * Update docs/content/en/working_with_findings/organizing_engagements_tests/tagging_objects.md Co-authored-by: Harold Blankenship <36673698+hblankenship@users.noreply.github.com> --------- Co-authored-by: Paul Osinski <paul.m.osinski@gmail.com> Co-authored-by: Cody Maffucci <46459665+Maffooch@users.noreply.github.com> Co-authored-by: Harold Blankenship <36673698+hblankenship@users.noreply.github.com>
1 parent 51c70e8 commit d9b49c5

3 files changed

Lines changed: 178 additions & 0 deletions

File tree

‎docs/assets/images/tags_importscan.png‎

142 KB
Loading

‎docs/assets/images/tags_product.png‎

113 KB
Loading

‎docs/content/en/working_with_findings/organizing_engagements_tests/tagging_objects.md‎

Lines changed: 178 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,178 @@
1+
---
2+
title: "Tags"
3+
description: "Use Tags to create a new slice of your data model"
4+
draft: false
5+
weight: 2
6+
exclude_search: false
7+
---
8+
9+
Tags are ideal for grouping objects in a manner that can be filtered out into smaller, more digestible chunks. They can be used to denote status, or to create custom sets of Product Type, Products, Engagements or Findings across the data model.
10+
11+
In DefectDojo, tags are a first class citizen and are recognized as the facilitators
12+
of organization within each level of the [data model](../Product_hierarchy).
13+
14+
Here is an example with a Product with two tags and four findings each with a single tag:
15+
16+
![High level example of usage with tags](images/tags-high-level-example.png)
17+
18+
### Tag Formats
19+
20+
Tags can be formatted in any of the following ways:
21+
- StringWithNoSpaces
22+
- string-with-hyphens
23+
- string_with_underscores
24+
- colons:acceptable
25+
26+
## Tag Management (Pro UI)
27+
28+
### Adding and Removing
29+
30+
Tags can be managed in the following ways:
31+
32+
1. **Creating or Editing new objects**
33+
34+
When a new object is created or edited through the UI or API, there is a field for specifying
35+
the tags to be set on a given object.
36+
37+
![tag](images/tags_product.png)
38+
39+
2. **When Importing/Reimporting Findings**
40+
41+
Tags are available on the Import/Reimport form, both in the UI and via the API. When this form is submitted, the **Test** will be tagged with `[tag]` and `[daily-import]`. If "Apply Tags to Findings" or "Apply Tags to Endpoints" is selected, those objects will also be tagged. Tags provide an opportunity to append automation run details and tool information that may not be captured in the Test or Finding object directly.
42+
43+
![tag](images/tags_importscan.png)
44+
45+
3. **Via Bulk Edit**
46+
47+
When many Findings are selected from a table, you can use the Bulk Edit menu to change the associated Tags for many Findings simultaneously. Note that this will replace all Finding-level Tags with the Tags specified; existing Finding Tags will be overwritten.
48+
49+
![bulk editing findings](images/Bulk_Editing_Findings.png)
50+
51+
For more information, see our guide to [Bulk Editing Findings](/en/working_with_findings/findings_workflows/editing_findings/#bulk-edit-findings).
52+
53+
54+
## Tag Management (Classic UI / OpenSource)
55+
56+
### Adding and Removing
57+
58+
Tags can be managed in the following ways:
59+
60+
1. Creating or Editing new objects
61+
62+
When a new object is created or edited through the UI or API, there is a field for specifying
63+
the tags to be set on a given object. This field is a multiselect field that also has
64+
auto completion to make searching and adding existing tags a breeze. Here is what the field
65+
looks like on the Product from the screenshot in the previous section:
66+
67+
![Tag management on an object](images/tags-management-on-object.png)
68+
69+
2. Import and Reimport
70+
71+
Tags can also be applied to a given test at the time of import or reimport. This is a very
72+
handy use case when importing via the API with automation as it provides an opportunity to
73+
append automation run details and tool information that may not be captured in the test
74+
or finding object directly.
75+
76+
The field looks and behaves exactly as it does on a given object
77+
78+
3. Bulk Edit Menu (Findings only)
79+
80+
When needing to update many Findings with the same set of tags, the bulk edit menu can be
81+
used to ease the burden.
82+
83+
In the following example, lets say I want to update the tags of the two findings with the tag "tag-group-alpha" to be a new tag list like this ["tag-group-charlie", "tag-group-delta"].
84+
First I would select the tags to be updated:
85+
86+
![Select findings for bulk edit tag update](images/tags-select-findings-for-bulk-edit.png)
87+
88+
Once a finding is selected, a new button appears with the name "Bulk Edit". Clicking this button
89+
produces a dropdown menu with many options, but the focus is just on tags for now. Update the
90+
field to have the desired tag list as follows, and click submit
91+
92+
![Apply changes for bulk edit tag update](images/tags-bulk-edit-submit.png)
93+
94+
The tags on the selected Findings will be updated to whatever was specified in the tags field
95+
within the bulk edit menu
96+
97+
![Completed bulk edit tag update](images/tags-bulk-edit-complete.png)
98+
99+
## Tag Inheritance
100+
101+
**Pro UI note: though Tag inheritance can be configured using the Pro UI, inherited Tags currently can only be accessed and filtered for through the Classic UI or the API.**
102+
103+
When Tag Inheritance is enabled, tags applied to a given Product will automatically be applied to all objects under Products in the [Product Hierarchy](/en/working_with_findings/organizing_engagements_tests/Product_hierarchy).
104+
105+
### Configuration
106+
107+
Tag Inheritance can be enabled at the following scope levels:
108+
- Global Scope
109+
- Every Product system wide will begin applying tags to all children objects (Engagements, Tests and Findings)
110+
- This is set within the System Settings
111+
- Product Scope
112+
- Only the selected Product will begin applying tags to all children objects (Engagements, Tests and Findings)
113+
- This is set at the Product creation/edit page
114+
115+
### Behaviors
116+
117+
When Tag Inheritance is enabled, standard Tags can be added to and removed from objects in the standard way.
118+
However inherited tags cannot be removed from a child object without removing them from the parent object
119+
See the following example of adding a tag "test_only_tag" to the Test object and a tag "engagement_only_tag" to the Engagement.
120+
121+
![Example of inherited tags](images/tags-inherit-exmaple.png)
122+
123+
When updates are made to the tag list on a Product, the same changes are made to all objects within the Product asynchronously. The duration of this task directly correlates to the number the objects contained within a finding.
124+
125+
**Open-Source:** If Tag changes are not observed within a reasonable time period, consult the celery worker logs to identify where any problems might have arisen.
126+
127+
128+
### Filtering for Tags (Classic UI)
129+
130+
Tags can be filtered in many ways through both the UI and the API. For example, here is a snippet
131+
of the Finding filters:
132+
133+
![Snippet of the finding filters](images/tags-finding-filter-snippet.png)
134+
135+
There are ten fields related to tags:
136+
137+
- Tags: filter on any tags that are attached to a given Finding
138+
- Examples:
139+
- Finding will be returned
140+
- Finding Tags: ["A", "B", "C"]
141+
- Filter Query: "B"
142+
- Finding Will *not* be returned
143+
- Finding Tags: ["A", "B", "C"]
144+
- Filter Query: "F"
145+
- Not Tags: filter on any tags that are *not* attached to a given Finding
146+
- Examples:
147+
- Finding will be returned
148+
- Finding Tags: ["A", "B", "C"]
149+
- Filter Query: "F"
150+
- Finding Will *not* be returned
151+
- Finding Tags: ["A", "B", "C"]
152+
- Filter Query: "B"
153+
- Tag Name Contains: filter on any tags that contain part or all of the query in the given Finding
154+
- Examples:
155+
- Finding will be returned
156+
- Finding Tags: ["Alpha", "Beta", "Charlie"]
157+
- Filter Query: "et" (part of "Beta")
158+
- Finding Will *not* be returned
159+
- Finding Tags: ["Alpha", "Beta", "Charlie"]
160+
- Filter Query: "meg" (part of "Omega")
161+
- Not Tags: filter on any tags that do *not* contain part or all of the query in the given Finding
162+
- Examples:
163+
- Finding will be returned
164+
- Finding Tags: ["Alpha", "Beta", "Charlie"]
165+
- Filter Query: "meg" (part of "Omega")
166+
- Finding Will *not* be returned
167+
- Finding Tags: ["Alpha", "Beta", "Charlie"]
168+
- Filter Query: "et" (part of "Beta")
169+
170+
For the other six tag filters, they follow the same rules as "Tags" and "Not Tags" as above,
171+
but at different levels in the data model:
172+
173+
- Tags (Test): filter on any tags that are attached to the Test of a given Finding
174+
- Not Tags (Test): filter on any tags that are *not* attached to the Test of a given Finding
175+
- Tags (Engagement): filter on any tags that are attached to the Engagement of a given Finding
176+
- Not Tags (Engagement): filter on any tags that are *not* attached to the Engagement of a given Finding
177+
- Tags (Product): filter on any tags that are attached to the Product of a given Finding
178+
- Not Tags (Product): filter on any tags that are *not* attached to the Product of a given Finding

0 commit comments

Comments
 (0)