@j-schreiber/sf-cli-security-audit 0.8.2 → 0.8.3

package/lib/ux/auditRunMultiStage.js

@@ -0,0 +1,120 @@
+import { MultiStageOutput } from '@oclif/multi-stage-output';
+import { capitalize } from '../libs/core/utils.js';
+export const LOAD_AUDIT_CONFIG = 'Loading audit config';
+export const RESOLVE_POLICIES = 'Resolving policies';
+export const EXECUTE_RULES = 'Executing rules';
+export const FINALISE = 'Formatting results';
+export default class AuditRunMultiStageOutput {
+    mso;
+    stageSpecificBlocks;
+    polStats;
+    constructor(opts) {
+        this.stageSpecificBlocks = opts.stageSpecificBlock;
+        this.mso = AuditRunMultiStageOutput.initUx(opts);
+        this.polStats = {};
+    }
+    /**
+     * In unit tests, we stub the actual UX class to hide output in terminal.
+     *
+     * @param opts
+     * @returns
+     */
+    static initUx(opts) {
+        return new MultiStageOutput(opts);
+    }
+    /**
+     * This pattern allows to stub multi-stage outputs in tests to mute output
+     * to stdout during test execution.
+     *
+     * In your code, create a new instance like this
+     * ```
+     * const ms = AuditRunMultiStageOutput.create(sobj, flags.json);
+     * ```
+     *
+     * @param opts
+     * @param jsonEnabled
+     * @returns
+     */
+    static create(opts) {
+        return new AuditRunMultiStageOutput({
+            jsonEnabled: opts.jsonEnabled ?? false,
+            stages: [LOAD_AUDIT_CONFIG, RESOLVE_POLICIES, EXECUTE_RULES, FINALISE],
+            title: 'Auditing Org',
+            preStagesBlock: [
+                {
+                    type: 'message',
+                    get: () => `Auditing ${opts.targetOrg} with config from ${opts.directoryRootPath}`,
+                },
+            ],
+            postStagesBlock: [
+                {
+                    type: 'static-key-value',
+                    label: 'Status',
+                    get: (data) => data?.currentStatus,
+                },
+            ],
+            stageSpecificBlock: [],
+        });
+    }
+    start() {
+        this.mso.goto(LOAD_AUDIT_CONFIG, { currentStatus: 'Initialising' });
+    }
+    startPolicyResolve(runInstance) {
+        this.mso.goto(RESOLVE_POLICIES, { currentStatus: 'Resolving' });
+        Object.entries(runInstance.configs.policies).forEach(([policyName, policy]) => {
+            if (policy.content.enabled) {
+                this.addPolicyStatsListener(policyName, runInstance);
+                this.stageSpecificBlocks.push({
+                    stage: RESOLVE_POLICIES,
+                    type: 'dynamic-key-value',
+                    label: capitalize(policyName),
+                    get: (data) => {
+                        if (data?.policies?.[policyName]) {
+                            return `${data.policies[policyName].resolved ?? 0}/${data.policies[policyName].total ?? 0}`;
+                        }
+                        else {
+                            return '';
+                        }
+                    },
+                });
+                if (policy.content.rules && Object.keys(policy.content.rules).length > 0) {
+                    const enabledRules = Object.values(policy.content.rules).filter((ruleConfig) => ruleConfig.enabled).length;
+                    this.stageSpecificBlocks.push({
+                        stage: EXECUTE_RULES,
+                        type: 'message',
+                        get: () => `Execute ${enabledRules} rule(s) for ${policyName}`,
+                    });
+                }
+            }
+        });
+        this.mso.updateData({});
+    }
+    startRuleExecution() {
+        this.mso.goto(EXECUTE_RULES, { currentStatus: 'Executing' });
+    }
+    finish() {
+        this.mso.goto(FINALISE, { currentStatus: 'Completed' });
+        this.mso.stop('completed');
+    }
+    addPolicyStatsListener = (policyName, runInstance) => {
+        // multi stage output updates its entire internal state, but only "patches"
+        // data one level deep (e.g. policies property is replaced entierly)
+        // thats why we gather the statistics for each individual policy in a single variable
+        // and then update the multi stage data with aggregated data
+        runInstance.addListener(`entityresolve-${policyName}`, (data) => {
+            if (this.polStats[policyName]) {
+                if (data.resolved) {
+                    this.polStats[policyName].resolved = data.resolved;
+                }
+                if (data.total) {
+                    this.polStats[policyName].total = data.total;
+                }
+            }
+            else {
+                this.polStats[policyName] = { resolved: data.resolved ?? 0, total: data.total ?? 0 };
+            }
+            this.mso.updateData({ policies: structuredClone(this.polStats) });
+        });
+    };
+}
+//# sourceMappingURL=auditRunMultiStage.js.map

package/lib/ux/auditRunMultiStage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auditRunMultiStage.js","sourceRoot":"","sources":["../../src/ux/auditRunMultiStage.ts"],"names":[],"mappings":"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"}

package/oclif.manifest.json

@@ -1,4 +1,255 @@
 {
-  "commands": {},
-  "version": "0.8.2"
+  "commands": {
+    "org:scan:user-perms": {
+      "aliases": [],
+      "args": {},
+      "description": "The target org is scanned \"in memory\" and searches Profiles and Permission Sets for the named user permissions. This command does not need an audit config and does not create a report file.",
+      "examples": [
+        "Search for multiple permissions on MyTargetOrg\n<%= config.bin %> <%= command.id %> -o MyTargetOrg -n AuthorApex -n ModifyMetadata"
+      ],
+      "flags": {
+        "json": {
+          "description": "Format output as json.",
+          "helpGroup": "GLOBAL",
+          "name": "json",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "flags-dir": {
+          "helpGroup": "GLOBAL",
+          "name": "flags-dir",
+          "summary": "Import flag values from a directory.",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "name": {
+          "char": "n",
+          "description": "You can specify any valid user permission on your org, such as \"AuthorApex\", \"CustomizeApplication\" or \"ViewSetup\". If you are unsure what permissions are available on your org, initialise a new audit config and check the created userPermissions.yml. Currently, the names are not validated: If you have a typo (such as \"AutorApex\", the scan will retun 0 results).",
+          "name": "name",
+          "required": true,
+          "summary": "One or more permissions to be searched for.",
+          "hasDynamicHelp": false,
+          "multiple": true,
+          "type": "option"
+        },
+        "target-org": {
+          "char": "o",
+          "name": "target-org",
+          "noCacheDefault": true,
+          "required": true,
+          "summary": "The target org to scan.",
+          "hasDynamicHelp": true,
+          "multiple": false,
+          "type": "option"
+        },
+        "api-version": {
+          "description": "Override the api version used for api requests made by this command",
+          "name": "api-version",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        }
+      },
+      "hasDynamicHelp": true,
+      "hiddenAliases": [],
+      "id": "org:scan:user-perms",
+      "pluginAlias": "@j-schreiber/sf-cli-security-audit",
+      "pluginName": "@j-schreiber/sf-cli-security-audit",
+      "pluginType": "core",
+      "strict": true,
+      "summary": "Performs a quick scan for specific user permissions.",
+      "enableJsonFlag": true,
+      "isESM": true,
+      "relativePath": [
+        "lib",
+        "commands",
+        "org",
+        "scan",
+        "user-perms.js"
+      ],
+      "aliasPermutations": [],
+      "permutations": [
+        "org:scan:user-perms",
+        "scan:org:user-perms",
+        "scan:user-perms:org",
+        "org:user-perms:scan",
+        "user-perms:org:scan",
+        "user-perms:scan:org"
+      ]
+    },
+    "org:audit:init": {
+      "aliases": [],
+      "args": {},
+      "description": "Uses your org's configuration to set up a new audit config at the target destination. This creates the basic classification and policy files that make up an audit config. You can select from presets to initialise risk levels with default values. After initialisation, you can customize the files to suit your needs.",
+      "examples": [
+        "Initialise audit policies at the root directory\n<%= config.bin %> <%= command.id %> -o MyTargetOrg",
+        "Initialise audit config at custom directory with preset\n<%= config.bin %> <%= command.id %> -o MyTargetOrg -d my_dir -p loose"
+      ],
+      "flags": {
+        "json": {
+          "description": "Format output as json.",
+          "helpGroup": "GLOBAL",
+          "name": "json",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "flags-dir": {
+          "helpGroup": "GLOBAL",
+          "name": "flags-dir",
+          "summary": "Import flag values from a directory.",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "target-org": {
+          "char": "o",
+          "name": "target-org",
+          "noCacheDefault": true,
+          "required": true,
+          "summary": "Target org to export permissions, profiles, users, etc.",
+          "hasDynamicHelp": true,
+          "multiple": false,
+          "type": "option"
+        },
+        "output-dir": {
+          "char": "d",
+          "name": "output-dir",
+          "required": false,
+          "summary": "Directory where the audit config is initialised. If not set, the root directory will be used.",
+          "default": "",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "preset": {
+          "char": "p",
+          "description": "The selected preset is applied before any other default mechanisms (such as template configs). This means, values from a selected template override the preset. Consult the documentation to learn more about the rationale behind the default risk levels. The risk levels interact with the configured preset on profiles and permission sets and essentially control, if a permission is allowed in a certain profile / permission set.",
+          "name": "preset",
+          "summary": "Preset to initialise defaults for permission risk levels.",
+          "default": "strict",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "options": [
+            "strict",
+            "loose",
+            "none"
+          ],
+          "type": "option"
+        },
+        "api-version": {
+          "description": "Override the api version used for api requests made by this command",
+          "name": "api-version",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        }
+      },
+      "hasDynamicHelp": true,
+      "hiddenAliases": [],
+      "id": "org:audit:init",
+      "pluginAlias": "@j-schreiber/sf-cli-security-audit",
+      "pluginName": "@j-schreiber/sf-cli-security-audit",
+      "pluginType": "core",
+      "strict": true,
+      "summary": "Initialise a new audit config.",
+      "enableJsonFlag": true,
+      "isESM": true,
+      "relativePath": [
+        "lib",
+        "commands",
+        "org",
+        "audit",
+        "init.js"
+      ],
+      "aliasPermutations": [],
+      "permutations": [
+        "org:audit:init",
+        "audit:org:init",
+        "audit:init:org",
+        "org:init:audit",
+        "init:org:audit",
+        "init:audit:org"
+      ]
+    },
+    "org:audit:run": {
+      "aliases": [],
+      "args": {},
+      "description": "Loads an existing audit config from the source directory and audits the target org. The audit run always creates a comprehensive report in JSON format.",
+      "examples": [
+        "Audit the org MyTargetOrg with the config in configs/prod\n<%= config.bin %> <%= command.id %> -o MyTargetOrg -d configs/prod"
+      ],
+      "flags": {
+        "json": {
+          "description": "Format output as json.",
+          "helpGroup": "GLOBAL",
+          "name": "json",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "flags-dir": {
+          "helpGroup": "GLOBAL",
+          "name": "flags-dir",
+          "summary": "Import flag values from a directory.",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "target-org": {
+          "char": "o",
+          "name": "target-org",
+          "noCacheDefault": true,
+          "required": true,
+          "summary": "The org that is audited.",
+          "hasDynamicHelp": true,
+          "multiple": false,
+          "type": "option"
+        },
+        "source-dir": {
+          "char": "d",
+          "name": "source-dir",
+          "required": false,
+          "summary": "Source directory of the audit config to run.",
+          "default": "",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "api-version": {
+          "description": "Override the api version used for api requests made by this command",
+          "name": "api-version",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        }
+      },
+      "hasDynamicHelp": true,
+      "hiddenAliases": [],
+      "id": "org:audit:run",
+      "pluginAlias": "@j-schreiber/sf-cli-security-audit",
+      "pluginName": "@j-schreiber/sf-cli-security-audit",
+      "pluginType": "core",
+      "strict": true,
+      "summary": "Audit your org with an existing config.",
+      "enableJsonFlag": true,
+      "isESM": true,
+      "relativePath": [
+        "lib",
+        "commands",
+        "org",
+        "audit",
+        "run.js"
+      ],
+      "aliasPermutations": [],
+      "permutations": [
+        "org:audit:run",
+        "audit:org:run",
+        "audit:run:org",
+        "org:run:audit",
+        "run:org:audit",
+        "run:audit:org"
+      ]
+    }
+  },
+  "version": "0.8.3"
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@j-schreiber/sf-cli-security-audit",
   "description": "Salesforce CLI plugin to automate highly configurable security audits",
-  "version": "0.8.2",
+  "version": "0.8.3",
   "repository": {
     "type": "https",
     "url": "https://github.com/j-schreiber/js-sf-cli-security-audit"

package/bin/dev.js

@@ -1,8 +0,0 @@
-#!/usr/bin/env -S node --loader ts-node/esm --no-warnings=ExperimentalWarning
-// eslint-disable-next-line node/shebang
-async function main() {
-  const { execute } = await import('@oclif/core');
-  await execute({ development: true, dir: import.meta.url });
-}
-
-await main();