PramanaDocumentation

For technical teams

Reference

For anyone who needs the exact name, column or rule. Everything here is in schema CORE (procedures, views, consoles) or schema GOV (tables) of the application, written as PRAMANA.CORE.… and PRAMANA.GOV.… when the application is installed as PRAMANA.

Pramana 1.011 min readDownload as PDF

Application roles#

RoleForCan
PRAMANA_ADMINPlatform or governance engineeringEverything: maintain the policy pack, run the engine, start and stop the schedule, load and clear the sample
PRAMANA_STEWARDData stewardsRead everything; decide proposals, acknowledge drift, add and close exemptions
PRAMANA_AUDITORAudit, risk, securityRead findings, drift, evidence packs and the policy pack
PRAMANA_EVIDENCE_READERA GRC tool's service roleRead CORE.PRAMANA_EVIDENCE_V and nothing else

Each role is granted what it needs directly. An admin can do everything a steward can, and a steward everything an auditor can.

ConsoleOpen toAdds
PRAMANA_VIEWER (the default)Admin, steward, auditorRead-only pages: Overview, Controls, Review queue, Drift, Evidence, Policy pack
PRAMANA_REVIEWAdmin, stewardApprove and reject proposals, acknowledge drift, add exemptions
PRAMANA_CONSOLEAdminSetup, Remediation, Run and Sample

What the application is granted#

GrantWhyWhen
EXECUTE TASK, EXECUTE MANAGED TASKOne serverless nightly taskAt install
SNOWFLAKE.OBJECT_VIEWERACCOUNT_USAGE.TABLES, COLUMNSYou grant it
SNOWFLAKE.GOVERNANCE_VIEWERTAG_REFERENCES, POLICY_REFERENCES, MASKING_POLICIES, ROW_ACCESS_POLICIES, DATA_CLASSIFICATION_LATESTYou grant it
SNOWFLAKE.SECURITY_VIEWERACCOUNT_USAGE.GRANTS_TO_ROLESYou grant it
READ SESSIONThe user name on review decisionsOptional

Procedures#

All in schema CORE.

ProcedureRoleWhat it does
GOV_RUN(action, options)AdminThe engine. options may be NULL
GOV_NIGHTLY()AdminThe whole chain in order. What the task calls
GOV_SCAN_AND_EVALUATE()AdminScan, classify and evaluate, without drift or evidence
GOV_START(), GOV_STOP()AdminCreate and resume, or suspend, the nightly task
GOV_STATUS()Admin, steward, auditorEdition, version, task state, last run
GOV_LOAD_CONFIG()AdminLoad the policy pack from CSV files on the application's stage
GOV_SAMPLE_LOAD(), GOV_SAMPLE_BREAK(), GOV_SAMPLE_RESTORE(), GOV_SAMPLE_CLEAR()AdminThe built-in sample
GOV_DECIDE(id, decision, note)StewardApprove or reject one proposal: APPROVE or REJECT
GOV_DECIDE_ALL(decision, min_confidence)StewardDecide every open proposal at or above HIGH, MEDIUM or LOW
GOV_ACKNOWLEDGE_DRIFT(id, note)StewardMark a drift event as reviewed
GOV_ADD_EXEMPTION(target, control, reason, expires)StewardAccept a finding until a date
GOV_CLOSE_EXEMPTION(target, control)StewardWithdraw an exemption

The actions of GOV_RUN:

ActionWhat it does
ACCESSReports what Pramana can read, with the GRANT statements still missing
VALIDATEChecks the policy pack against itself and lists problems and warnings
SCANTakes a snapshot of the metadata of the databases in scope
CLASSIFYProposes a category for columns that look sensitive and are not tagged. Closes an approved proposal once its tag is on the column
EVALUATEEvaluates every control against the latest snapshot
DRIFTCompares the latest snapshot with the one before it
EVIDENCEWrites one evidence pack per framework
REMEDIATEWrites the statements that would close the open findings and the approved proposals still waiting for their tag
NIGHTLYScan, classify, evaluate, drift and evidence, in order
PURGERemoves snapshots, and what was built on them, older than EVIDENCE_RETENTION_DAYS
SAMPLEUsed by the GOV_SAMPLE_… procedures

Views#

View (schema CORE)What it answers
GOV_CONTROL_STATUS_VThe thirteen controls: latest status, counts, note
GOV_FINDING_LATEST_VEvery failure, warning and exemption of the latest evaluation, with its action
GOV_COVERAGE_VColumns, tagged and masked, per database and schema
GOV_SENSITIVE_COLUMN_VEvery tagged column with its category, the bound policy and what is attached
GOV_TAG_VEvery table against every governed tag: the value it carries, where the tag is set, the rank the pack gives that value and whether the pack lists it
GOV_REVIEW_QUEUE_VOpen proposals
GOV_DRIFT_OPEN_VUnacknowledged drift, weakening first
GOV_EVIDENCE_LATEST_VThe newest pack per framework, as JSON and Markdown
GOV_REMEDIATION_OPEN_VThe latest batch, still to do, in order (STEP): statements ready to run, policy templates to complete, and what waits for them. No rows when the latest run found nothing left to do
GOV_SNAPSHOT_LATEST_VThe newest snapshot
PRAMANA_EVIDENCE_VThe contract for GRC tooling: one row per pack with coverage, weakening count, open proposals, controls and the clause map

The tables behind the views are in schema GOV and readable by every role except the evidence reader.

The policy pack tables#

Ten tables in schema GOV. A holder of PRAMANA_ADMIN has INSERT, UPDATE and DELETE on them. They can also be loaded from CSV files, one file per table, named after the table in lower case.

GOV_SETTING#

KeyMeaningDefault
CLASSIFICATION_TAGFully qualified tag whose value is the categoryEmpty
INCLUDE_VIEWSScan views as well as tablesFALSE
CLASSIFY_MIN_CONFIDENCEHIGH, MEDIUM or LOW: the lowest classifier confidence that countsMEDIUM
CLASSIFICATION_STALE_DAYSCLS-04: how old a classifier result may be, in days30
NIGHTLY_SCHEDULEThe task's schedule. Call GOV_START again after changing itUSING CRON 0 2 * * * UTC
FRAMEWORKSFrameworks a pack is built for on each run, comma separatedGDPR_UK,DORA
GOVERNED_OWNER_ROLESACC-02: a regular expression your table-owning roles matchSee below
BROAD_GRANTEESACC-01: roles whose SELECT on a sensitive table is a finding, comma separatedPUBLIC
MAX_FAILURES_IN_PACKFailures listed in full per control in a pack200
EVIDENCE_RETENTION_DAYSWhat PURGE keeps1100

The default for GOVERNED_OWNER_ROLES matches roles whose name begins DATA_OWNER_ or ends _OWNER.

CATALOG_SOURCE, CLASSIFY_ON_SCAN and REMEDIATION_MODE belong to the standalone edition and are ignored inside the application. EDITION, VERSION, RUNNING, SAMPLE_ACTIVE and DEFAULT_PACK_SEEDED are Pramana's own bookkeeping.

GOV_SCOPE#

DATABASE_NAME, SCHEMA_INCLUDE_REGEX, SCHEMA_EXCLUDE_REGEX, TABLE_EXCLUDE_REGEX, ENABLED. The three expressions are case-insensitive regular expressions; SCHEMA_INCLUDE_REGEX defaults to .*.

GOV_CATEGORY#

The taxonomy.

ColumnMeaning
CATEGORYFor example PII_EMAIL
PRIVACY_LEVELIDENTIFIER, QUASI_IDENTIFIER, SENSITIVE, or NONE (never counts as sensitive)
TAG_VALUEThe value of the classification tag that means this category. Usually the same name
CLASSIFIER_CATEGORIESSnowflake semantic categories that map here, for example EMAIL
NAME_REGEXCase-insensitive regular expression searched in the column name, for example E_?MAIL

It ships with PII_NAME, PII_EMAIL, PII_PHONE, PII_ADDRESS, PII_DOB, PII_NATIONAL_ID, FIN_ACCOUNT, HEALTH and INTERNAL. Rename, add or remove freely.

GOV_BINDING#

CATEGORY, MASKING_POLICY (fully qualified; empty means none required), ROW_ACCESS_POLICY, RAP_COLUMN (the column the policy takes), ENABLED. A category without a binding is governed (the classification controls apply) but not protected (no policy is required); VALIDATE warns, so the gap is a decision and not an accident.

GOV_TAG#

The table-level tags you govern by, one row each.

ColumnMeaning
TAG_CLASSWhat the tag is for, as one word of at most 24 characters: RETENTION, RESIDENCY, OWNER. It names the tag in findings, drift events (residency_tag_removed) and evidence
TAG_NAMEThe tag, fully qualified. Empty: the tag is not evaluated and its controls are skipped. It cannot be the classification tag, and two rows cannot name the same tag
REQUIRED_ONWhich tables must carry it: SENSITIVE (tables holding sensitive columns; the default) or ALL (every table in scope)
MISSING_CONTROLThe control that fails a table that needs the tag and carries no value. Empty: presence is not checked
VALUE_CONTROLThe control that fails a value GOV_TAG_VALUE does not list. Empty: values are not checked
WEAKER_WHENHIGHER or LOWER: which direction of VALUE_RANK weakens your position, for drift. Empty: the values are not ranked
RANK_UNITWhat VALUE_RANK counts, as the evidence pack prints it (days)
DESCRIPTION, ENABLED

Control ids are yours to choose, up to 20 characters, and cannot be one of the eleven built-in ids. Two tags may share a control, if you want one control to answer for both.

GOV_TAG_VALUE#

TAG_CLASS, TAG_VALUE (a value the tag may carry), VALUE_RANK (optional: where the value stands), DESCRIPTION, ENABLED. A tag with no row here accepts any value. For retention the rank is the number of days the class keeps data, and WEAKER_WHEN is HIGHER: the evidence pack states the period of each class in use, and a change of class counts as weakening when the new class keeps the data longer. A value listed without a rank (a legal hold) counts as the weakest. For a tag ranked the other way, a confidentiality tier for instance, set WEAKER_WHEN = LOWER.

GOV_CONTROL#

CONTROL_ID, ENABLED, SEVERITY (FAIL or WARN). The catalogue is Pramana's; you switch a control off or re-grade it. The controls your own governed tags name are added to it by VALIDATE, and re-graded the same way afterwards.

GOV_FRAMEWORK#

FRAMEWORK, CONTROL_ID, CLAUSE, CLAUSE_TITLE. Add your own framework as rows and name it in FRAMEWORKS.

GOV_EXEMPTION#

TARGET (DB.SCHEMA.TABLE or DB.SCHEMA.TABLE.COLUMN; a table-level row covers its columns), CONTROL_ID, REASON, APPROVED_BY, EXPIRES. An exemption whose EXPIRES date has passed no longer applies.

GOV_EVIDENCE_SOURCE#

SOURCE_NAME, SOURCE_TYPE (VIGIL or VIEW), OBJECT_FQN, ENABLED. Type VIEW samples any view the application can read into the pack. A pack carries the row count of such a view and a sample of up to twenty of its rows, so name only views whose contents belong in an evidence pack.

Controls#

IdFamilyTitleDefault grade
CLS-01ClassificationSensitive columns carry the classification tagFail
CLS-02ClassificationTag values are from the taxonomyFail
CLS-03ClassificationClassifier agrees with the tagWarn
CLS-04ClassificationClassification is currentWarn
POL-01PolicyTagged columns have the bound masking policyFail
POL-02PolicyTables with row-access categories carry the bound policyFail
POL-03PolicyMasking policies sit only on tagged columnsWarn
POL-04PolicyBound policies exist and are referencedFail
ACC-01AccessNo broad grants on sensitive tablesFail
ACC-02AccessSensitive tables are owned by a governed roleWarn
RET-01RetentionTables that need one carry a retention classFail
RET-02RetentionRetention classes are from the packFail
DQ-01QualityReconciliation evidence is green for sensitive tablesFail

What makes each one fail, and what closes it:

IdNon-compliant whenWhat closes it
CLS-01A column with no tag is detected as a sensitive categoryTag it, or reject the proposal
CLS-02A tag value is not one of the taxonomy'sDecide: add the value as a category, or retag
CLS-03A tagged column is detected as a different category (warning)A steward's eye
CLS-04A sensitive table has no classifier result within CLASSIFICATION_STALE_DAYS (warning)Classify it
POL-01A tagged column's masking policy is not the one bound to its categoryAttach the bound policy
POL-02A table holds a category that binds a row access policy, and lacks itAttach it
POL-03A masking policy sits on an untagged column (warning)Tag the column, or exempt it
POL-04A bound policy does not exist, or is attached nowhere in scopeCreate it, or fix the binding
ACC-01A broad grantee holds SELECT, ALL or OWNERSHIP on a sensitive tableRevoke
ACC-02A sensitive table's owner is not a governed role (warning)Transfer ownership
RET-01A table holding sensitive data (or any table, when the RETENTION row of GOV_TAG says REQUIRED_ON = ALL) carries no retention class. Skipped until GOV_TAG names the retention tagGive the table its class, where you govern your data
RET-02A table carries a retention value that GOV_TAG_VALUE does not list. Skipped without a retention tag or without classesCorrect the tag, or add the class to the pack
YoursThe two controls of each governed tag you add: a table that needs the tag carries none; a value the pack does not listSet or correct the tag, where you govern your data
DQ-01Vigil's latest reconciliation check on a sensitive table fails. Skipped without VigilReconcile

Statuses: PASS, FAIL or WARN per control; EXEMPT per finding (counted, listed in the pack, never fails); SKIPPED per control, with the reason in its note. Control ids never change, because auditors cite them.

Drift events#

EventRecorded whenCounts as weakening
table_added, table_removedA table enters or leaves the scanned estateNo
owner_changedA table's owner changesWhen the table is sensitive and the new owner is not a governed role
column_added, column_removedA column appears or disappearsNo
sensitive_column_addedA new column is detected as sensitive and carries no tagYes
tag_added, tag_changedA column gains a classification, or its value changesNo
tag_removedA column loses its classificationYes
masking_addedA masking policy is attached to a columnNo
masking_changed, masking_removedA column's masking policy is replaced or detachedYes
rap_addedA row access policy is attached to a tableNo
rap_removedA row access policy is detachedYes
grant_addedA privilege is granted on a tableWhen the table is sensitive and the privilege is SELECT, ALL or OWNERSHIP
grant_removedA privilege is revokedNo
<class>_tag_addedA table gains a governed tag, for example retention_tag_addedNo
<class>_tag_changedThe value of a governed tag changesWhen the new value ranks weaker, by the tag's WEAKER_WHEN
<class>_tag_removedA table loses a governed tagYes

Policy attachments that appear only because Snowflake's metadata caught up with the account are not reported as drift.

Remediation statuses#

StatusMeaning
PROPOSEDA statement that can run as written
TEMPLATEA CREATE … POLICY for a policy the pack binds and the account does not have. The body is a placeholder for you to complete
BLOCKEDA statement that is correct and cannot run until the policy from a template exists

The evidence pack#

Each pack is one row of GOV.GOV_EVIDENCE_PACK: PACK_ID, GENERATED_AT, SNAPSHOT_ID, RUN_ID, FRAMEWORK, OVERALL, BASELINE_SNAPSHOT, PACK_SHA256, PACK (JSON) and PACK_MD (the readable pack).

Key in PACKContent
pack_id, generated_at, product, framework, overall, snapshot, run_idThe header. overall is FAIL if any control fails, WARN if any warns, otherwise PASS
coverageColumns, tagged, sensitive detected, untagged detections, masked, coverage percentages, per database; and governed_tags, one entry per governed tag
controlsPer control: title, family, severity, status, counts, clauses, failures (target, status, message, action) and how many were left out
framework_mapPer clause: title, controls, and the worst status of those controls
driftBaseline snapshot, counts, and each event, weakening first
exemptionsEvery exemption in force: target, control, reason, approver, expiry
reviewOpen, approved, applied and rejected proposal counts
evidence_sourcesVigil's reconciliation summary where linked; for other views, a row count and a sample
integrityalgorithm (sha256), value, and what the value covers

The seal is the SHA-256 of the pack without its integrity block, with whole numbers written without a decimal point, serialised as JSON with sorted keys. verify_pack.py, on the documentation page, recomputes it; the Evidence Guide shows how.

Log lines#

Written to your account's event table, if you have one.

LineLevelWhen
pramana.runINFOOnce per engine run
pramana.weakeningWARNINGWhen a run finds weakening drift, with the number of events and the two snapshots compared