diff --git a/docs/7-administration/billing/security-products.md b/docs/7-administration/billing/security-products.md new file mode 100644 index 000000000..34bffcedc --- /dev/null +++ b/docs/7-administration/billing/security-products.md @@ -0,0 +1,155 @@ +# Email Security and Code Security billing + +Email Security and Code Security have separate paid coverage. Paying for endpoint +security or another product does not automatically buy either one. Enabling an +extension starts setup; paid coverage requires explicit price acceptance and +confirmation from the protection service. + +| Product | Paid rate | New organization trial | +|---|---|---| +| Email Security | $1 per protected mailbox-month | 14 days, up to 25 mailboxes | +| Code Security | $0.80 per protected repository-month, plus the existing Cloud Security base fee | 14 days, up to 10 repositories | + +Trials cover the organization across its connections. Shared mailboxes and repeated +references to the same repository count once when they have the same stable identity. +Code includes hosted repositories and external scanner imports; container images do +not contribute to this repository meter. Telemetry and other services remain separately +priced. The console shows the organization's actual Cloud base fee; it is not included +in the $0.80 rate. + +## Trial and coverage + +A new trial starts at the first protected resource. Unsubscribing, resubscribing or +restarting a connection does not restart it. Use the server's trial deadline and +coverage status instead of calculating entitlement from a browser clock. + +Organizations enabled before billing enforcement receive a fresh 14-day trial from +the enforcement instant. Their existing protected set stays free for those 14 days, +including sets above 25 mailboxes or 10 repositories. This exception preserves the +existing set; it does not allow unlimited expansion or swapping in an unlimited number +of new resources. New organizations and growth beyond that baseline follow the normal +limits. Existing paid protection is not silently converted into a new charge without +price acceptance. + +Use Email Security mailbox scope and exclusions to choose coverage. Code's scanning +settings select repository coverage. Review resources that are discovered but not +protected; a successful configuration save is not proof that protection has started. +When eligibility expires, unpaid protection can pause. Configuration and existing +data follow the product's retention policy and scheduled-deletion notices. Review +those notices before the deadline; paying does not retroactively analyze work missed +while coverage was paused. + +## Purchase and check acknowledgement + +In **Billing & Usage**, or the product's overview, review trial status, protected +count, limits and the current rates. Add a payment method through the billing page +(or use authorized invoicing), then select the price-acceptance checkbox and +**Activate paid coverage**. + +Billing status requires `org.get` and `billing.ctrl`. Changing paid coverage also +requires `user.ctrl`. Analysts without billing permission can still inspect product +coverage and trial information through the product's read surface without access to +payer or financial details. + +A request can remain **Pending** while billing or protection reconciles. Do not treat +an HTTP success or a saved configuration as paid coverage. Refresh until the server +reports acknowledged paid protection. A failed or unavailable response does not +establish coverage; correct the payment method or contact support as indicated. +An HTTP 200 mutation with `acknowledged: false` is committed but pending; poll GET +until its control settles and protection matches the requested change. HTTP 503 +is retryable after refreshing status and does not confirm paid coverage. Activation +may be temporarily unavailable during rollout while reads and stop remain available. + +The billing API uses the same routes for both products: + +| Operation | Route | +|---|---| +| Status and cost | `GET /v1/orgs/{oid}/billing/security/{product}` | +| Accept pricing and request activation | `POST /v1/orgs/{oid}/billing/security/{product}` with `{"accept_pricing":true,"accepted_quote":}` | +| Request paid stop | `DELETE /v1/orgs/{oid}/billing/security/{product}` | + +`product` is `mail_security` or `code_security`. Optional GET parameters `from` and +`until` must be supplied together as UTC dates `YYYY-MM-DD`. The beginning is +inclusive, the end exclusive, and the maximum range is 366 days. Without a custom +range, use the returned billing period; an invoice interval can differ from a calendar +month. The normalized `status` contains phase, acknowledged protection, trial limits, +pending control, rates and costs. Fields whose authority is unavailable are omitted +or null; do not interpret missing fields as paid or as zero cost. + +### Accept the exact quoted price + +GET returns `status.quote_guard_version: 1` and `status.pricing_quote`. All nine +quote fields are required: `version`, `quote_id`, `product`, `currency`, +`monthly_cents`, `days_per_month`, `cloud_base_monthly_cents`, `meter_price_id`, +and `cloud_price_id`. Email's Cloud amount is `0` and price ID is an empty string; +these fields are still required. Review the rates and send the entire quote unchanged +in `accepted_quote`. Its opaque ID binds organization, payer and billing mode as +well as prices. It accepts rates, not a fixed future population or monthly total. + +If pricing changed, POST returns HTTP 409 `reason: security_quote_changed` before +recording consent or performing purchase effects. Refetch GET, review the new quote, +and obtain fresh consent. The console clears its checkbox. Do not silently accept +a freshly fetched replacement quote. Missing pricing or an unsupported quote guard +pauses purchasing. + +With a CLI version supporting quoted purchases, save the quote you will review: + +```sh +limacharlie billing security get mail_security --oid --output json > security-status.json +python3 -c 'import json; s=json.load(open("security-status.json")); assert s["status"]["quote_guard_version"] == 1; print(json.dumps(s["status"]["pricing_quote"], indent=2))' > accepted-quote.json +cat accepted-quote.json +# After reviewing the quote: +limacharlie billing security activate mail_security --accepted-quote accepted-quote.json --accept-pricing --oid --output yaml +limacharlie billing security get mail_security --oid --output yaml +# Explicit manual stop; then poll GET for acknowledgement: +limacharlie billing security stop mail_security --confirm --oid --output yaml +``` + +Use `code_security` for Code; its quote also discloses the separate Cloud fee. +The SDK class `limacharlie.sdk.billing.Billing` accepts `Billing(org).activate_security("mail_security", accept_pricing=True, +accepted_quote=reviewed_quote)`, with the complete quote from +`Billing(org).get_security("mail_security")`. Both surfaces preserve pending +responses and API errors instead of claiming that purchase has completed. + +## How cost is calculated + +Each UTC day uses the **highest paid protected resource count** reached that day. +Removing resources later that day does not erase the day's peak. Trials are free; +trial observed counts do not become billable resource-days. + +The monthly resource rate is divided by a fixed **30** to price each resource-day. +The billing period sums daily peaks and rounds the resulting period amount; it does +not round each resource-day to whole cents. + +For example, one paid mailbox protected throughout a 31-day period contributes +31 mailbox-days: `31 × $1 / 30 = $1.0333…`, or approximately **$1.03** before other +charges. One repository contributes `31 × $0.80 / 30 = $0.8266…`, approximately +**$0.83**, plus the separate Cloud base fee. A 28-day period contributes 28/30 of +the resource's monthly rate when coverage stays constant. + +The console labels today's count **provisional** because its high-water mark can +still increase. Closed days are settled separately. Accrued cost is an estimate, not +a finalized invoice or the total across telemetry, Cloud fees, tax, discounts and +other products. See the invoice for the final amount. + +## Stop, payment failure and recovery + +**Stop paid coverage** requests an end to future paid eligibility. Check the returned +pending control and refresh until the protection service acknowledges the stop. +Already accrued usage remains payable; the final day's peak is preserved. Stopping +does not reset the trial or immediately erase configuration and data. Any remaining +valid trial or grant can still permit unpaid coverage under its limits. + +Stopping Code paid coverage **keeps the separate Cloud Security subscription and +base fee**. Stopping that subscription is a separate operation and also affects Code +eligibility. Do not assume the repository stop removes every Cloud charge. + +A first failed payment does not immediately remove existing paid protection. Owners +are notified while Stripe retries, with a maximum seven-day grace. Protection stops +at terminal unpaid/canceled status or the grace deadline. Scheduled cancellation +keeps coverage until its effective end. Payment recovery can resume previously +consented, payment-suspended coverage; it does not undo a voluntary product stop. + +Keep the billing contact and payment method current, and inspect pending or suspended +status promptly. Neither a payment-method update nor a callback alone proves that +protection has resumed: verify the authoritative product acknowledgement. diff --git a/docs/cloud-security/code-security/getting-started.md b/docs/cloud-security/code-security/getting-started.md index 85c684a0d..3f7b087c7 100644 --- a/docs/cloud-security/code-security/getting-started.md +++ b/docs/cloud-security/code-security/getting-started.md @@ -233,3 +233,18 @@ If a repository stays unscanned, see [Troubleshooting](troubleshooting.md). - [Working with results](results.md): triage what the first scan found. - [Pull-request checks and push rescans](pull-requests.md): catch problems before they merge. - [AutoFix pull requests](autofix.md): have LimaCharlie open dependency upgrades. + +## Trial, coverage and billing + +Code Security has independent paid repository coverage: $0.80 per protected +repository-month plus the existing Cloud Security base fee. A new organization +receives a 14-day trial for up to 10 repositories across hosted connections and +external imports. Container images do not contribute to the repository meter. +Existing enabled organizations receive the fresh trial and preserved-set grant +at enforcement; their deadline is not backdated to an old Cloud trial. + +In Billing & Usage or Code Security, inspect the canonical trial limit and +acknowledged protection, choose coverage in scanning settings, and explicitly +accept pricing to activate paid coverage. The separate Cloud entitlement and +base fee remain distinct. See [Security product billing](../../7-administration/billing/security-products.md) +for daily high-water marks, cost calculation, payment grace and stopping coverage. diff --git a/docs/email-security/getting-started.md b/docs/email-security/getting-started.md index a18558022..6a0f606c2 100644 --- a/docs/email-security/getting-started.md +++ b/docs/email-security/getting-started.md @@ -26,16 +26,18 @@ A **credential** is the key the product uses to access your mail provider. A **secret** is the securely stored copy of that credential in LimaCharlie. A **connection** combines that secret with your provider and mailbox choices. -!!! info "Trial limits" - Free-tier organizations can try Email Security for **14 days**, with up to - **25 mailboxes**. The clock starts when you subscribe, and resubscribing does - not restart it. Prepare your administrator access first. At expiry ingestion - pauses; data is removed 30 days later unless the organization moves off the - free tier. See [trial details](policy.md#plans-the-free-trial-and-the-mailbox-cap). - - During private beta, limits may be reported before enforcement is enabled. - Check the Overview trial/coverage information (or `coverage.entitlement` - from the API) for the standing actually in force in your organization. +!!! info "Trial and independent paid coverage" + New organizations receive **14 days** for up to **25 mailboxes**, starting + at the first protected mailbox. Resubscribing does not restart the trial. + Existing enabled organizations receive a fresh 14-day trial at enforcement + with their current protected set preserved. See + [Security product billing](../7-administration/billing/security-products.md). + + Paid Email Security requires explicit pricing acceptance and protection + acknowledgement; endpoint security quota does not buy it. At effective trial + expiry unpaid ingestion may pause and data follows the product's retention + and scheduled-deletion policy. Check actual trial and coverage status rather + than assuming a configuration save establishes protection. ## 1. Enable Email Security diff --git a/docs/email-security/policy.md b/docs/email-security/policy.md index b7d0dad8f..f951b458a 100644 --- a/docs/email-security/policy.md +++ b/docs/email-security/policy.md @@ -602,14 +602,14 @@ server from your verified claims rather than taken from the request. | Event | When the data is deleted | What cancels it | |---|---|---| | The organization unsubscribes from Email Security | **30 days** later | Resubscribing at any point inside those 30 days | -| The organization's free trial ends and it stays on the free tier | **30 days** later | Moving the organization off the free tier at any point inside those 30 days | +| The effective Email Security trial ends without paid coverage | **30 days** later | Acknowledged paid Email Security eligibility inside those 30 days | | The organization itself is deleted | Immediately | Nothing — the organization no longer exists | None of them needs anyone to ask. The 30-day delay exists so that unsubscribing by mistake, letting a trial lapse over a holiday, or moving billing around is recoverable — and undoing the thing that started the clock is all the recovery takes. The two cancellations are **not interchangeable**: resubscribing does not -cancel a deletion scheduled because a trial ended, and upgrading does not cancel +cancel a deletion scheduled because a trial ended, and paid activation does not cancel one scheduled because the organization unsubscribed. Each undoes only what it contradicts. @@ -633,76 +633,51 @@ re-sent for the new date. ## Plans, the free trial, and the mailbox cap -Email Security is in private beta and must be available to your organization -before you subscribe. For an enabled organization, what differs between a -**trial** organization and a **paid** one is how long it runs and how many -mailboxes it protects. - -An organization is on the trial when it is on the LimaCharlie free tier — the -same line the rest of the platform draws, so an organization evaluating Email -Security and Cloud Security at once gets one answer about what it is paying for. +Email Security must be available to your organization before setup. It has an +independent paid product: **$1 per protected mailbox-month**, divided by 30 per +UTC mailbox-day. Paying for endpoint security or increasing its quota does not +activate paid Email Security. See [Security product billing](../7-administration/billing/security-products.md) +for price acceptance, payment methods, costs and pending acknowledgements. | | Trial | Paid | |---|---|---| -| Duration | **14 days** from the day Email Security was enabled | No trial duration limit | -| Protected mailboxes | **25** | No plan-imposed mailbox cap | -| Everything else — detections, remediation, retention, API, telemetry | Identical | Identical | +| Duration | **14 days** from the first protected mailbox for new organizations | No trial duration limit | +| Protected mailboxes | **25** across the organization | No trial mailbox cap | +| Product features | Identical | Identical | -These are the trial terms. During beta, a deployment can report limits before -enforcing them. Read `coverage.entitlement` for your actual standing and -enforcement; a reported limit alone does not prove ingestion has paused. Contact -LimaCharlie to confirm trial or scheduled-deletion enforcement in your data -region. Policy records and a CLI installation cannot enable server enforcement. +Organizations enabled before enforcement get a fresh 14-day trial from the +enforcement instant. Their existing protected set remains free for those 14 days, +including a set above 25. The exception preserves that set; new organizations and +expansion beyond the permitted baseline follow the standard cap. ### The 14-day clock -The clock starts the day the organization first subscribes to -`ext-email-security` and is recorded durably. **Unsubscribing and resubscribing -does not restart it**: the clock survives an unsubscribe, so a trial is 14 days -once rather than 14 days per subscription. Moving the organization off the free -tier clears the limits immediately. - -Read the remaining time from the `entitlement` block of -[`GET /coverage`](api-reference.md#reads): `trial_ends_at` and -`trial_days_remaining`. +The server records trial eligibility durably. **Unsubscribing and resubscribing +does not restart it.** Read the canonical deadline and remaining days from the +product coverage surface or billing status; a browser clock is not entitlement +authority. Existing-organizations' fresh trial is a once-only grant, not a reset +available on each subscription. ### What happens when the trial ends -The same thing that happens when an organization unsubscribes, and for the same -reason — the product stops, nothing is deleted yet: - -- **Ingestion pauses.** No new mail is analyzed, and the mail connections are - not renewed, so the provider's own watches expire on their own schedule. -- **Nothing is deleted, and nothing is changed.** The connections, the policy - records and every message already analyzed are intact and follow their normal - [retention](#data-retention-and-deletion). -- **Reading and acting still work.** An analyst can still search the queue, read - a message and remediate mail that was already ingested. -- **The 30-day deletion clock starts**, with the notices described above. - -Moving the organization off the free tier resumes ingestion within about five -minutes, and cancels the scheduled deletion. Mail delivered while ingestion was -paused is not analyzed retroactively. +Unpaid ingestion can pause when the effective trial expires. Configuration and +previously analyzed mail remain subject to [data retention and deletion](#data-retention-and-deletion), +including scheduled-deletion notices and grace. Reading and acting on retained +messages remain available to authorized analysts. Explicit paid activation resumes +eligible protection after acknowledgement; it does not retroactively analyze +mail delivered while ingestion was paused. ### The 25-mailbox cap -A trial organization protects up to 25 mailboxes. The cap applies to the whole -organization, across every connected mail tenant, and it works on **activation** -only: - -- Discovery still finds every mailbox in the tenant — the ones past the cap are - reported as `discovered` rather than `protected`, so you can see exactly how - much of the estate is not covered. -- A mailbox that is already protected is **never** dropped to fit a cap. If the - cap is reached, further mailboxes stop being protected; the ones already being - watched keep being watched. -- Use [`exclusions`](#exclusions) and the connection's `scope` to choose *which* - 25 mailboxes matter — the executives and finance addresses attacks aim at are - the ones worth spending a trial on. - -`GET /coverage`'s `entitlement` block reports `mailbox_cap`, `mailboxes_active`, -`mailboxes_over_cap` and `mailbox_cap_reached`, so the shortfall is a number -rather than a discovery. +A new trial protects up to 25 distinct mailboxes across all connections. Discovery +can find more than the protected set. Use connection scope and +[`exclusions`](#exclusions) to choose coverage, and inspect `GET /coverage` for +what is actually protected. Renames and shared references use stable provider +identities, rather than billing each address spelling separately. + +Read the server's actual enforcement and pending state. During rollout, a +reported limit alone does not prove ingestion has paused. Contact support if +reported entitlement and observed collection disagree. ### Requesting a purge diff --git a/docs/email-security/setup-cli.md b/docs/email-security/setup-cli.md index 8cdcbf01d..2d85da12e 100644 --- a/docs/email-security/setup-cli.md +++ b/docs/email-security/setup-cli.md @@ -33,25 +33,21 @@ create automation policy records. With no automation policy, automatic actions are off; a new automation rule defaults to `alert_only`, so it records intent without moving mail. See [Policy Reference](policy.md). -!!! info "Free trial: 14 days, 25 mailboxes" - An organization on the LimaCharlie free tier gets Email Security in full for - **14 days** and protects up to **25 mailboxes** while it does. Every feature - is the same as on a paid plan; only the duration and the mailbox count - differ. The clock starts the day you subscribe and **does not restart if you - unsubscribe and resubscribe**, so point the 25 at the mailboxes that matter - — start with the executives, finance and the abuse mailbox. - - When the trial ends, ingestion pauses and nothing is deleted; the data is - removed 30 days later unless the organization moves off the free tier, and - you are told before that happens. The full rules, and the exact fields to - read the countdown from, are in - [Plans, the free trial, and the mailbox cap](policy.md#plans-the-free-trial-and-the-mailbox-cap). - - During private beta, trial limits may be reported before enforcement is - enabled. Check `mailsec coverage` and its `entitlement` block for your - organization's actual standing and enforcement. Contact LimaCharlie if the - reported state and collection behavior disagree; saving a connection alone - does not establish trial eligibility. +!!! info "Trial and independent paid coverage" + New organizations receive 14 days with up to 25 protected mailboxes, starting + at the first protected mailbox. Unsubscribe/resubscribe does not restart the + trial. Existing enabled organizations receive the once-only fresh trial and + preserved baseline described in [Security product billing](../7-administration/billing/security-products.md). + + Email Security paid coverage is independent of endpoint security quota. + Review and accept $1 per protected mailbox-month, calculated using UTC daily + high-water marks and a fixed 30-day month, through Billing & Usage. Inspect + coverage and billing status until protection is acknowledged; saving a + connection or receiving a pending response does not establish coverage. + + At expiry unpaid ingestion may pause, with data retained under the product's + retention and deletion policy. Read [Plans, the free trial, and the mailbox cap](policy.md#plans-the-free-trial-and-the-mailbox-cap) + and scheduled-deletion notices before the deadline. ## 2. Grant the permissions @@ -274,8 +270,7 @@ entitlement: ``` `mailboxes_over_cap` is the number that matters: those mailboxes were found and -are not being watched. Narrow the connection's `scope`, or move off the free -tier. See +are not being watched. Narrow the connection's `scope`, or explicitly activate paid Email Security. See [Plans, the free trial, and the mailbox cap](policy.md#plans-the-free-trial-and-the-mailbox-cap). !!! note "Backfill is judged, and acts on nothing" diff --git a/mkdocs.yml b/mkdocs.yml index c491c04b9..2deeb6e31 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -521,6 +521,7 @@ nav: - SSO: 7-administration/access/sso.md - Billing: - Options: 7-administration/billing/options.md + - Security Products: 7-administration/billing/security-products.md - Custom Plans: 7-administration/billing/custom-plans.md - Estimating Data Ingestion: 7-administration/billing/data-estimation.md - Config Hive: