Skip to main content

Live-org setup

This page is for the admin or developer who has scanned source code with vulkro-sf scan and now wants the live-org pass: the posture, identity, and packages detectors that read configuration straight out of a running org.

The connector is optional. Source-only scans cover the Code pillar (Apex, LWC, Aura, Visualforce, Flow) without needing any org access. The live-org pass adds the four remaining pillars: Posture, Identity, Third-party, and AI / Agentforce-runtime context.

Install the Salesforce CLI​

vulkro-sf does not authenticate to Salesforce itself. It hands off to the official Salesforce CLI (sf), which already has the audited OAuth flow, refresh-token handling, and credential store.

macOS​

brew install salesforce-cli

Linux, Windows, macOS (via npm)​

npm install -g @salesforce/cli

Verify​

sf --version

If sf is not on PATH when you invoke vulkro-sf org, the error message prints the exact install command for your platform.

Authenticate the org​

Authenticate once per org. The sf CLI opens a browser, you complete the standard Salesforce OAuth dance, and sf stores the refresh token in its credential store on your laptop.

Production org​

sf org login web --alias my-prod

Sandbox​

sf org login web \
  --alias my-sandbox \
  --instance-url https://mycompany--sandbox.sandbox.my.salesforce.com

Scratch org​

Scratch orgs are typically authenticated through sf org create scratch --definition-file ..., which authenticates automatically. If you need to re-attach to an existing scratch org:

sf org login web \
  --alias my-scratch \
  --instance-url https://my-scratch-org.scratch.my.salesforce.com

The --alias is the handle you pass to --target-org later. Pick a short, memorable string.

List your authenticated orgs​

sf org list

The output lists every org sf has a token for, marks the default, and prints the alias and username. Pick the alias you want to scan.

Test the connection​

Before running the per-pillar live-org subcommands, confirm the plumbing works end-to-end:

vulkro-sf org status --target-org my-prod

The command:

  1. Asks the sf CLI for the refreshed access token (the token never transits Vulkro itself; sf performs the metadata fetch).
  2. Pulls the org's identity (Org ID, instance URL, type, edition, trial expiry if any).
  3. Prints a one-line ready-or-not summary.

A success line looks like:

Org my-prod (00D5g000004XXXXAAA): Production, Enterprise Edition. Ready.

If vulkro-sf cannot reach the org, the error message states which of the five common causes is the most likely (sf not on PATH, alias not authenticated, refresh token expired, instance URL changed, network blocked) and the exact sf command to recover.

Run the live-org passes​

Once org status succeeds, the remaining live-org subcommands take the same --target-org flag:

vulkro-sf org perms    --target-org my-prod
vulkro-sf org packages --target-org my-prod
  • org perms runs the Identity pillar: profile and permission-set over-privilege analysis, permset-group aggregation risk, and the "ghost admin" check (a System Administrator that has not logged in within the rolling window).
  • org packages runs the Third-party pillar: installed managed and unmanaged packages with version, license, namespace, and beta or prerelease state. Surfaces packages whose namespace matches a known high-risk vendor breach class (the Drift / Gainsight bucket).

Each subcommand follows the same exit-code contract as scan: 0 = no findings, 1 = findings, 2 = error.

In the desktop console (vulkro-sf serve)​

The same live-org reads power the Orgs section of the desktop console. After sf org login web, run vulkro-sf serve, open the console, and the org appears under Orgs with read-only tabs:

  • Identity: profile and permission-set over-privilege, ghost admins.
  • Posture: SecuritySettings hardening (session timeout, IP binding, clickjack, CSRF, password policy) plus per-profile login IP ranges. The hardening values are read live; a setting the scan cannot read produces no finding, never a guessed one.
  • Connected Apps: OAuth scope and refresh-token risk.
  • Packages: installed managed and unmanaged packages.
  • Agentforce: bot and GenAiPlugin inventory.

Audits: snapshot and diff over time​

Click Run audit on an org to capture a point-in-time snapshot of its posture. Each snapshot is stored, so the Audits tab shows the full history and a "changes since the previous audit" diff (what is NEW and what was RESOLVED). Re-run before and after a hardening change to prove the delta.

The console shows only what the audit actually found: real findings or an honest empty state, never sample data.

Source plus live org in one scan​

Run a source scan with an org selected ("Source + live org" mode) and the live-org posture findings merge into the same scan result as the Apex / LWC / Flow findings, so one Findings list and one risk score cover both the code you wrote and the running org.

Run vulkro-sf serve from a shell whose PATH includes sf: the console shells out to the official CLI for every org read.

Privacy: what the connector reads, what it does not, where the token lives​

The org connector is metadata-only. The wording below is precise on purpose: anything the scanner reads is named in the first list, anything it never reads is named in the second.

What vulkro-sf org reads​

  • Profiles and Permission Sets (including assignments).
  • Permission Set Groups.
  • SecuritySettings (session timeout, clickjack, CSRF, HTTPS, password policy, login IP ranges).
  • Sharing rules and org-wide defaults.
  • Connected Apps and their OAuth scopes.
  • Named Credentials and External Credentials.
  • Flow definitions and process automation.
  • GenAiFunction declarations (Agentforce actions) and the target Apex class metadata.
  • Installed packages (managed and unmanaged) with version, license, and namespace.
  • Static Resources (for hardcoded-API-key scanning).
  • SAML SSO and Auth Provider configuration.
  • Login Flows and Login IP Ranges.
  • RemoteSiteSetting, CorsWhitelistOrigin, CspTrustedSite.

Every item above comes from the Salesforce Metadata API or the Tooling API. No SOQL or Bulk queries are issued against business records.

What vulkro-sf org does NOT read​

  • No customer records of any kind.
  • No Accounts, Opportunities, Leads, Cases, Contacts, custom-object rows.
  • No file attachments, ContentVersions, ContentDocuments.
  • No SOQL SELECT against any sObject that contains business data.
  • No Bulk API queries.
  • No User records beyond what is needed to identify the System Administrator population for the dormant-admin check (username, LastLoginDate, IsActive, Profile).
  • No EmailMessage, Task, or Event content.
  • No reports, dashboards, or list views.

Where the OAuth token lives​

In the official sf CLI credential store, on your laptop. The storage location is the standard sf keychain entry on macOS, the encrypted DPAPI store on Windows, and the libsecret-backed keyring on Linux (the same location any other sf CLI command reads from).

The flow is:

  1. vulkro-sf calls sf and asks it to perform a metadata fetch against the named alias.
  2. sf refreshes the access token if needed and issues the API call.
  3. sf returns the metadata response to vulkro-sf.
  4. vulkro-sf runs the detectors against the response in memory.

Vulkro never sees the access token, never stores it, never transmits it. Revoke org access through Salesforce Setup the same way you would for the sf CLI itself: Setup -> Connected Apps OAuth Usage -> Salesforce CLI -> Revoke.

Network egress​

The live-org subcommands talk to your Salesforce instance only. The scanner does not call the Vulkro CDN, the Vulkro license server, or any third-party endpoint during a live-org scan. Air-gapped runners work without additional configuration.

Per-command references​

The CLI deep-dives carry the full flag set, return-shape contract, and exit-code matrix per subcommand:

Where to go next​

  • CI/CD integration: wire org status and org perms into a nightly pipeline so the live-org pass runs on a schedule, not only on demand.
  • AppExchange readiness report: merge the source-only findings and the live-org findings into one pre-submission HTML deliverable.
  • Methodology: the coverage matrix shows which detectors require the live org and which run on source alone.