feat(security-center): Add Resource v2 API Security Marks Samples (#3835

)

* Add Resource v2 security marks samples

* feat(security marks): Add Resource v2 API Security Marks Samples

* remove mentioning the v2 path from workflows

* Address Suggestions

* fix lint error

* Address suggestions

* fix lint error

---------

Co-authored-by: Tony Pujals <subfuzion@users.noreply.github.com>
Co-authored-by: Adam Ross <adamross@google.com>

security-center/snippets/system-test/v2/securityMarks.test.js

@@ -0,0 +1,132 @@
+// Copyright 2024 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+'use strict';
+
+const {SecurityCenterClient} = require('@google-cloud/security-center').v2;
+const {assert} = require('chai');
+const {describe, it, before} = require('mocha');
+const {execSync} = require('child_process');
+const exec = cmd => execSync(cmd, {encoding: 'utf8'});
+
+const organizationId = process.env.GCLOUD_ORGANIZATION;
+
+describe('Client with SourcesAndFindings', async () => {
+  let data;
+  before(async () => {
+    // Creates a new client.
+    const client = new SecurityCenterClient();
+    const [source] = await client
+      .createSource({
+        source: {
+          displayName: 'Customized Display Name',
+          description: 'A new custom source that does X',
+        },
+        parent: client.organizationPath(organizationId),
+      })
+      .catch(error => console.error(error));
+    const eventTime = new Date();
+    const createFindingTemplate = {
+      parent: source.name,
+      findingId: 'somefinding',
+      finding: {
+        state: 'ACTIVE',
+        // Resource the finding is associated with.  This is an
+        // example any resource identifier can be used.
+        resourceName: `//cloudresourcemanager.googleapis.com/organizations/${organizationId}`,
+        // A free-form category.
+        category: 'MEDIUM_RISK_ONE',
+        // The time associated with discovering the issue.
+        eventTime: {
+          seconds: Math.floor(eventTime.getTime() / 1000),
+          nanos: (eventTime.getTime() % 1000) * 1e6,
+        },
+      },
+    };
+    const [finding] = await client.createFinding(createFindingTemplate);
+    createFindingTemplate.findingId = 'untouchedFindingId';
+    createFindingTemplate.finding.category = 'XSS';
+    const [untouchedFinding] = await client
+      .createFinding(createFindingTemplate)
+      .catch(error => console.error(error));
+    const sourceId = source.name.split('/')[3];
+    const findingId = finding.name.split('/')[7];
+
+    data = {
+      orgId: organizationId,
+      sourceName: source.name,
+      findingName: finding.name,
+      untouchedFindingName: untouchedFinding.name,
+      sourceId: sourceId,
+      findingId: findingId,
+    };
+    console.log('My data security marks %j', data);
+  });
+
+  it('client can add security marks to finding v2', done => {
+    const output = exec(
+      `node v2/addFindingSecurityMarks.js ${data.orgId} ${data.sourceId}`
+    );
+    assert(output.includes(data.orgId));
+    assert(output.includes(data.sourceId));
+    assert.match(output, /key_a/);
+    assert.match(output, /value_a/);
+    assert.match(output, /key_b/);
+    assert.match(output, /value_b/);
+    assert.notMatch(output, /undefined/);
+    done();
+  });
+
+  it('client can list findings with security marks v2', done => {
+    // Ensure marks are set.
+    exec(`node v2/addFindingSecurityMarks.js ${data.orgId} ${data.sourceId}`);
+    const output = exec(
+      `node v2/listFindingsWithSecurityMarks.js ${data.orgId} ${data.sourceId}`
+    );
+    assert(!output.includes(data.findingName));
+    assert(output.includes(data.untouchedFindingName));
+    assert.notMatch(output, /undefined/);
+    done();
+  });
+
+  it('client can delete and update findings with security marks v2', done => {
+    // Ensure marks are set.
+    exec(`node v2/addFindingSecurityMarks.js ${data.orgId} ${data.sourceId}`);
+    const output = exec(
+      `node v2/deleteAndUpdateSecurityMarks.js ${data.orgId} ${data.sourceId}`
+    );
+    assert(output.includes(data.orgId));
+    assert.match(output, /key_a/);
+    assert.match(output, /new_value_for_a/);
+    assert.notMatch(output, /key_b/);
+    assert.notMatch(output, /value_b/);
+    assert.notMatch(output, /undefined/);
+    done();
+  });
+
+  it('client can delete and update findings with security marks v2', done => {
+    // Ensure marks are set.
+    exec(`node v2/addFindingSecurityMarks.js ${data.orgId} ${data.sourceId}`);
+    const output = exec(
+      `node v2/deleteSecurityMarks.js ${data.orgId} ${data.sourceId}`
+    );
+    assert(output.includes(data.orgId));
+    assert.notMatch(output, /key_a/);
+    assert.notMatch(output, /value_a/);
+    assert.notMatch(output, /key_b/);
+    assert.notMatch(output, /value_b/);
+    assert.notMatch(output, /undefined/);
+    done();
+  });
+});

security-center/snippets/v2/addFindingSecurityMarks.js

@@ -0,0 +1,61 @@
+// Copyright 2024 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+'use strict';
+
+/**
+ * Demostrates adding security marks to a finding.
+ */
+function main(
+  organizationId,
+  sourceId,
+  location = 'global',
+  findingId = 'somefinding'
+) {
+  // [START securitycenter_add_finding_security_marks_v2]
+  // Imports the Google Cloud client library.
+  const {SecurityCenterClient} = require('@google-cloud/security-center').v2;
+
+  // Creates a new client.
+  const client = new SecurityCenterClient();
+
+  // Build the full resource path for the finding to update.
+  /*
+   * TODO(developer): Update the following references for your own environment before running the sample.
+   */
+  // const organizationId = 'YOUR_ORGANIZATION_ID';
+  // const sourceId = 'SOURCE_ID';
+  const findingName = `organizations/${organizationId}/sources/${sourceId}/locations/${location}/findings/${findingId}`;
+
+  // Construct the request to be sent by the client.
+  const updateSecurityMarksRequest = {
+    securityMarks: {
+      name: `${findingName}/securityMarks`,
+      marks: {key_a: 'value_a', key_b: 'value_b'},
+    },
+    // Only update the marks with these keys.
+    updateMask: {paths: ['marks.key_a', 'marks.key_b']},
+  };
+
+  async function addFindingSecurityMarks() {
+    const [newMarks] = await client.updateSecurityMarks(
+      updateSecurityMarksRequest
+    );
+
+    console.log('New marks: %j', newMarks);
+  }
+  addFindingSecurityMarks();
+  // [END securitycenter_add_finding_security_marks_v2]
+}
+
+main(...process.argv.slice(2));

security-center/snippets/v2/deleteAndUpdateSecurityMarks.js

@@ -0,0 +1,66 @@
+// Copyright 2024 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+'use strict';
+
+/**
+ * Demostrates updating and deleting security marks to a finding.
+ */
+function main(
+  organizationId,
+  sourceId,
+  location = 'global',
+  findingId = 'somefinding'
+) {
+  // [START securitycenter_add_delete_security_marks_v2]
+  // Imports the Google Cloud client library.
+  const {SecurityCenterClient} = require('@google-cloud/security-center').v2;
+
+  // Creates a new client.
+  const client = new SecurityCenterClient();
+
+  // Build the full resource path for the finding to update.
+  /*
+   * TODO(developer): Update the following references for your own environment before running the sample.
+   */
+  // const organizationId = 'YOUR_ORGANIZATION_ID';
+  // const sourceId = 'SOURCE_ID';
+  const findingName = `organizations/${organizationId}/sources/${sourceId}/locations/${location}/findings/${findingId}`;
+
+  // Construct the request to be sent by the client.
+  const updateSecurityMarksRequest = {
+    securityMarks: {
+      name: `${findingName}/securityMarks`,
+      marks: {key_a: 'new_value_for_a'},
+    },
+    // Set the update mask to specify which properties should be updated.
+    // If empty, all mutable fields will be updated.
+    // For more info on constructing field mask path, see the proto or:
+    // https://cloud.google.com/java/docs/reference/protobuf/latest/com.google.protobuf.FieldMask.
+    // Since no marks have been added, including "marks.key_b" in the update mask
+    // will cause it to be deleted.
+    updateMask: {paths: ['marks.key_a', 'marks.key_b']},
+  };
+
+  async function UpdateAndDeleteSecurityMarks() {
+    const [newMarks] = await client.updateSecurityMarks(
+      updateSecurityMarksRequest
+    );
+
+    console.log('New marks: %j', newMarks);
+  }
+  UpdateAndDeleteSecurityMarks();
+  // [END securitycenter_add_delete_security_marks_v2]
+}
+
+main(...process.argv.slice(2));

security-center/snippets/v2/deleteSecurityMarks.js

@@ -0,0 +1,62 @@
+// Copyright 2024 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+'use strict';
+
+/**
+ * Demostrates deleting security marks on a finding.
+ */
+function main(
+  organizationId,
+  sourceId,
+  location = 'global',
+  findingId = 'somefinding'
+) {
+  // [START securitycenter_delete_security_marks_v2]
+  // Imports the Google Cloud client library.
+  const {SecurityCenterClient} = require('@google-cloud/security-center').v2;
+
+  // Creates a new client.
+  const client = new SecurityCenterClient();
+
+  // Build the full resource path for the finding to update.
+  /*
+   * TODO(developer): Update the following references for your own environment before running the sample.
+   */
+  // const organizationId = 'YOUR_ORGANIZATION_ID';
+  // const sourceId = 'SOURCE_ID';
+  const findingName = `organizations/${organizationId}/sources/${sourceId}/locations/${location}/findings/${findingId}`;
+
+  // Construct the request to be sent by the client.
+  const updateSecurityMarksRequest = {
+    securityMarks: {
+      name: `${findingName}/securityMarks`,
+      // Intentionally, not setting marks to delete them.
+    },
+    // Only delete marks for the following keys.
+    updateMask: {paths: ['marks.key_a', 'marks.key_b']},
+  };
+
+  async function deleteSecurityMarks() {
+    const [newMarks] = await client.updateSecurityMarks(
+      updateSecurityMarksRequest
+    );
+
+    console.log('Updated marks: %j', newMarks);
+  }
+  deleteSecurityMarks();
+  // [END securitycenter_delete_security_marks_v2]
+}
+
+main(...process.argv.slice(2));

security-center/snippets/v2/listFindingsWithSecurityMarks.js

@@ -0,0 +1,62 @@
+// Copyright 2024 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+'use strict';
+
+/** Demonstrates listing findings by filtering on security marks. */
+function main(organizationId, sourceId) {
+  // [START securitycenter_list_findings_with_security_marks_v2]
+  // Imports the Google Cloud client library.
+  const {SecurityCenterClient} = require('@google-cloud/security-center').v2;
+
+  // Creates a new client.
+  const client = new SecurityCenterClient();
+  //  Build the full resource path for the source to search for findings.
+
+  // The source path supports mutliple formats:
+  // - `${parent}/sources/${sourceId}` without a location
+  // - `${parent}/sources/${sourceId}/locations/${location}` with a location
+  // where parent must be in one of the following formats:
+  // - `organizations/${organization_id}`
+  // - `folders/${folder_id}`
+  // - `projects/${project_id}`
+
+  /*
+   * TODO(developer): Update the following references for your own environment before running the sample.
+   */
+  // const organizationId = 'YOUR_ORGANIZATION_ID';
+  // const sourceId = 'SOURCE_ID';
+
+  const sourceName = `organizations/${organizationId}/sources/${sourceId}`;
+
+  // Construct the request to be sent by the client.
+  const listFindingsRequest = {
+    // List findings across all sources.
+    parent: sourceName,
+    filter: 'NOT security_marks.marks.key_a="value_a"',
+  };
+
+  async function listFindingsWithSecurityMarks() {
+    const [response] = await client.listFindings(listFindingsRequest);
+    let count = 0;
+    Array.from(response).forEach(result =>
+      console.log(
+        `${++count} ${result.finding.name} ${result.finding.resourceName}`
+      )
+    );
+  }
+  listFindingsWithSecurityMarks();
+  // [END securitycenter_list_findings_with_security_marks_v2]
+}
+
+main(...process.argv.slice(2));