OPERATIONS

Operations guide

This guide turns the command reference into an operating procedure. It is not a substitute for organizational authorization, incident procedures, or evidence retention policy. It helps an authorized operator make the collection request small, reviewable, and reproducible.

Operating model

Every request follows the same path:

scope decision -> preflight -> plan review -> explicit authorization -> isolated run -> manifest review -> evidence handoff

The command-line interface does not infer authorization from a profile. The --acknowledge-authorization flag is required for collection because the final scope decision belongs to the operator. It must follow, not replace, a review of the plan.

Choose the smallest useful request

Use a mode only when its complete membership fits the question. Inspect the live matrix with:

python -m logicytics --modes

Then create a non-collecting plan. The five modes are quick, balanced, standard, offline, and thorough.

python -m logicytics plan --mode standard

Use a direct collector for a single known question, such as host inventory:

python -m logicytics collector core.system.system_info --acknowledge-authorization

Use repeated --include and --exclude when the standard profile is close but not exact. Keep an exported plan or the terminal transcript with the case notes so another reviewer can reproduce the scope.

Review capabilities before authorization

Capabilities describe access a collector may request. They are not just labels: a requested block prevents matching collectors from entering the plan. The available CLI capability values are:

• filesystem_read, filesystem_write, registry_read, and subprocess
• network and packet_capture
• browser_data, sensitive_files, and private_keys
• elevated_privileges

For a restricted collection, request explicit blocks and plan again:

python -m logicytics plan --mode thorough `
  --block-capability browser_data `
  --block-capability sensitive_files `
  --block-capability private_keys `
  --block-capability packet_capture

Configuration can also define persistent blocks. Invocation blocks add to those configured restrictions; they do not weaken them. Read Safety and the catalog entry for every sensitive collector you leave selected.

Run and observe

Run the reviewed request with acknowledgement:

python -m logicytics run --mode standard `
  --acknowledge-authorization

The runtime gives each collector its own worker process, workspace, temporary directory, event channel, and resource boundary. An independent collector failure is recorded rather than normally terminating unrelated collectors. That is why an apparently successful run must still be inspected collector by collector.

For diagnosis, make concurrency explicit:

python -m logicytics run --mode standard --sequential `
  --acknowledge-authorization

--performance-check performs serial measurement and saves per-collector durations; it is a measurement mode, not a shortcut. --no-package leaves the durable run directory and manifest but intentionally omits the ZIP. --reboot and --shutdown are high-impact post-run actions: they are mutually exclusive and only occur after successful package publication.

Extensions and removable media

Plugins are opt-in because they are user-owned collector code. Include them only after their source, metadata, and capability declarations have been reviewed:

python -m logicytics preflight --plugins
python -m logicytics plan --mode standard --plugins

Use --usb [DRIVE] only when deliberately targeting a Windows installation on removable storage. The engine rejects unsafe output, cache, and temporary paths on that target. Confirm the chosen drive and keep output on separately approved storage before authorizing the run.

Handle the outcome

Exit code is a routing signal, not the full result:

Exit code	Meaning	Operator action
0	Requested command completed successfully	Review the manifest and artifacts before handoff.
1	Collection completed with a non-success run status	Review failed, partial, skipped, or cancelled records; preserve useful artifacts.
2	Command, configuration, preflight, or planning failure	Correct the indicated input or source; do not bypass the gate.
130	Interrupted	Locate the manifest and determine what was safely finalized before retrying.

Finish every collection with Evidence Review. If an error is not self-explanatory, follow Troubleshooting and retain only sanitized diagnostic material for support.