使用自訂驗證器在Adaptive Forms中掃描檔案附件

[AEM Forms]{class="badge positive" title="套用至AEM Forms"}

檔案附件病毒掃描程式/驗證程式功能屬於早期採用者程式。 您可以使用官方電子郵件 ID 寫信至 aem-forms-ea@adobe.com，以加入早期採用者計劃並要求存取該功能。

最適化Forms可在提交時將每個上傳的附件傳遞至您選擇的驗證器。 驗證器在伺服器上執行，在記憶體中接收檔案，並決定接受或拒絕提交，因此不會持續儲存惡意或不相容的檔案。 因為您提供驗證器，所以您可以連線到任何您已經使用的防毒引擎、惡意程式碼掃描程式或自訂驗證邏輯。

本文說明此功能、記錄您實作的FileAttachmentValidator介面，並逐步說明如何建立防毒驗證器。 如需完整的引擎特定範例，請參閱隨附教學課程使用ClamAV掃描檔案附件。

運作方式 how-it-works

當使用者提交已選取驗證器的調適型表單時，AEM會在處理提交之前叫用您上傳附件的驗證器：

此模型的兩個屬性對安全性而言很重要：

可用性和先決條件 prerequisites

FileAttachmentValidator介面 interface-reference

您藉由實作com.adobe.forms.common.service.FileAttachmentValidator並將其註冊為OSGi服務來新增驗證器。 介面會定義兩種方法。

FileAttachmentVeritor fileattachmentvalidator

FileAttachmentWrapper fileattachmentwrapper

包裝函式可讓您的程式碼存取已上傳的檔案及其中繼資料。 一般驗證器中使用的存取子包括：

FileAttachmentValidationResult fileattachmentvalidationresult

您的驗證器傳回FileAttachmentValidationResult以告知架構是否接受附件。 使用下列引數建構它：

例如：new FileAttachmentValidationResult(false, "The attached file failed the security scan.", wrapper)。

FileAttachmentValidatormanager fileattachmentvalidatormanager

AEM註冊單一FileAttachmentValidatorManager服務，該服務位於架構與您部署的每個驗證器之間。 您通常不需要自行呼叫： AEM會使用呼叫來查詢在表單上選取的驗證器，並加以叫用。 瞭解何時進行疑難排解會很有用，因為這是提交索引標籤的下拉式清單和核心提交管道兩者的流程。

註冊OSGi服務 register-service

為實作加上註解，使其在FileAttachmentValidator介面下註冊。 部署後，驗證器就可在您的表單上選取。

建置防毒驗證器 build-validator

下列實作會顯示驗證程式的結構，而不會將其繫結至特定引擎。 以呼叫您的防毒、掃描API或驗證服務來取代scanWithYourEngine方法。

package com.example.forms.security;

import com.adobe.forms.common.service.FileAttachmentValidator;
import com.adobe.forms.common.service.FileAttachmentValidationResult;
import com.adobe.forms.common.service.FileAttachmentWrapper;
import org.osgi.service.component.annotations.Component;

@Component(service = FileAttachmentValidator.class)
public class CustomFileAttachmentValidator implements FileAttachmentValidator {

    private static final String VALIDATOR_NAME = "Custom Antivirus Scanner";

    @Override
    public FileAttachmentValidationResult validateFileAttachment(FileAttachmentWrapper wrapper) {

        if (wrapper == null) {
            return new FileAttachmentValidationResult(false, "No attachment was received.", wrapper);
        }

        byte[] content = wrapper.getValue();
        if (content == null || content.length == 0) {
            return new FileAttachmentValidationResult(false, "The attached file is empty.", wrapper);
        }

        try {
            boolean clean = scanWithYourEngine(content);
            if (clean) {
                return new FileAttachmentValidationResult(true, "File passed the security scan.", wrapper);
            }
            return new FileAttachmentValidationResult(false,
                    "The attached file failed the security scan and was rejected.", wrapper);

        } catch (Exception e) {
            // Fail closed: if the scanner cannot be reached, reject rather than let an
            // unscanned file through. See Best practices for the fail-open alternative.
            return new FileAttachmentValidationResult(false,
                    "The file could not be scanned at this time. Please try again later.", wrapper);
        }
    }

    @Override
    public String getFileAttachmentValidatorName() {
        return VALIDATOR_NAME;
    }

    /**
     * Integrate your antivirus or validation engine here.
     * Return true if the file is safe to accept, false if it should be rejected.
     */
    private boolean scanWithYourEngine(byte[] content) {
        // TODO: call a local scanning daemon (for example over a socket)
        // or a remote scanning API, and interpret its verdict.
        return true;
    }
}

建置和部署套件組合 build-deploy

編譯專案並安裝套件，以便在AEM執行個體上註冊驗證器。

在開發期間部署至本機執行個體。 從您的專案根目錄，建置並安裝套件組合至執行中的編寫執行個體：

mvn clean install -PautoInstallBundle

autoInstallBundle設定檔將編譯的套件組合推送到本機AEM執行個體（預設為http://localhost:4502）。 如果您的執行個體在不同主機、連線埠或證明資料上執行，請將它們傳遞至組建，例如：

mvn clean install -PautoInstallBundle -Daem.host=localhost -Daem.port=4502 -Dvault.user=admin -Dvault.password=admin

部署至更高的環境。 對於測試和生產，請勿手動安裝套件。 透過CI/CD管道將其部署為專案的all內容套件的一部分。 如需完整程式，請參閱部署至AEM as a Cloud Service。

確認服務已註冊。 開啟元件主控台並搜尋您的驗證器類別：

http://localhost:4502/system/console/components

元件應列示其狀態，顯示為​active （或​satistified），已在FileAttachmentValidator服務下註冊。 如果不滿意，請參閱確認您的驗證程式載入並執行中。

將驗證器欄位新增至表單對話方塊 add-dialog-field

本節適用於以​ 核心元件 ​為基礎的最適化Forms。 檔案附件病毒掃描程式/驗證器​欄位不在現成的最適化表單容器對話方塊中。 您可在自己的專案中將其新增一次，作為小型擴充功能。 您之後部署的每個驗證器（請參閱建置防毒驗證器）接著會自動顯示為選項；請勿對每個驗證器重複此步驟。

您專案的最適化表單容器是​Proxy元件： /apps下使用sling:resourceSuperType指向真實核心元件的元件，例如：

<!-- /apps/<project>/components/adaptiveForm/formcontainer/.content.xml -->
<?xml version="1.0" encoding="UTF-8"?>
<jcr:root xmlns:jcr="http://www.jcp.org/jcr/1.0"
    jcr:primaryType="cq:Component"
    jcr:title="Form Container"
    sling:resourceSuperType="core/fd/components/form/container/v2/container"
    xmlns:sling="http://sling.apache.org/jcr/sling/1.0"/>

由於sling:resourceSuperType，您可以新增​ 一個新欄位 ​至繼承的[提交]索引標籤，而不複製整個對話方塊。 Sling Resource Merger只需要重新建立一直到插入點的節點名稱路徑。 請參閱一般機制的延伸元件對話方塊。 真正的OOTB提交索引標籤會將其欄位保留在content/items/tabs/items/submitActions/items/columns/items/下，所以這是映象的路徑：

<!-- /apps/<project>/components/adaptiveForm/formcontainer/_cq_dialog/.content.xml -->
<?xml version="1.0" encoding="UTF-8"?>
<jcr:root xmlns:jcr="http://www.jcp.org/jcr/1.0" xmlns:sling="http://sling.apache.org/jcr/sling/1.0"
    jcr:primaryType="nt:unstructured">
  <content jcr:primaryType="nt:unstructured">
    <items jcr:primaryType="nt:unstructured">
      <tabs jcr:primaryType="nt:unstructured">
        <items jcr:primaryType="nt:unstructured">
          <submitActions jcr:primaryType="nt:unstructured">
            <items jcr:primaryType="nt:unstructured">
              <columns jcr:primaryType="nt:unstructured">
                <items jcr:primaryType="nt:unstructured">
                  <fileAttachmentValidator
                      jcr:primaryType="nt:unstructured"
                      sling:resourceType="granite/ui/components/coral/foundation/form/select"
                      fieldLabel="File Attachment Virus Scanner/Validator"
                      fieldDescription="Select a registered validator configuration to scan submitted file attachments. Select None to disable validation for this form."
                      emptyText="None"
                      name="./fileAttachmentValidator">
                    <datasource
                        jcr:primaryType="nt:unstructured"
                        sling:resourceType="<project>/datasources/fileattachmentvalidators"/>
                  </fileAttachmentValidator>
                </items>
              </columns>
            </items>
          </submitActions>
        </items>
      </tabs>
    </items>
  </content>
</jcr:root>

值得一提的兩個細節：

datasource子節點指向您也編寫的小型Sling servlet。 它有一個工作：向FileAttachmentValidatorManager詢問getValidators()，並將每個驗證器的getFileAttachmentValidatorName()轉換為下拉式選項。 如需完整、準備就緒的實作，請參閱ClamAV教學課程的步驟7：不論您使用哪個驗證器引擎，servlet都相同，因此您可以依原樣將其複製到專案中。

將這兩個檔案部署為您專案的ui.apps內容套件和core套件組合的一部分（請參閱建置並部署套件組合）。 部署後，此對話方塊擴充功能已驗證運作正常：欄位會與現有OOTB欄位一起顯示在「提交」標籤上（而非取代它們），且將其設定為會儲存引導容器節點上的純fileAttachmentValidator屬性，AEM提交管道會透過FileAttachmentValidatorManager.getFileAttachmentValidator(name)讀取該屬性。

在您的表單上選取驗證器 select-validator

執行階段行為和使用者體驗 runtime-behavior

驗證您的驗證器是否載入並執行 verify

如果​ File Attachment Virus Scanner / Validator ​欄位本身未出現在[提交]索引標籤上：

如果欄位出現，但您的驗證器未列在下拉式清單中：

最佳實務和考量事項 best-practices

決定掃描的位置。 您的驗證器可呼叫在本機（或與AEM同置）或遠端掃描API執行的掃描引擎。 本機或異地引擎可在您的環境中保留檔案內容，協助滿足資料駐留及法規遵循需求。 遠端API會將檔案位元組傳送至環境外，因此請先確認資料的可接受性，然後再進行選擇。

刻意選擇失敗模式。 當掃描引擎無法連線或發生錯誤時，您可以關閉失敗（如上述範例所示，拒絕檔案）或開啟失敗（接受）。 對於安全性敏感型表單而言，「關閉失敗」是較安全的預設值。 失敗開放偏好的可用性。 選擇明確而非意外。

考慮延遲。 掃描會在提交期間同步進行，因此掃描時間會新增至使用者的提交體驗。 如果您依賴外部服務，請設定致電引擎的合理逾時，並以服務等級協定來設定期望值。

已繫結承載。 getValue()會以記憶體中byte[]的形式傳回檔案，因此大型上傳會消耗棧積。 使用檔案附件元件的檔案大小上限和支援的檔案型別來限制來源上的上傳，因此驗證器只會處理大小合理、預期的檔案。

將控制項分層。 驗證器是數層中最強的一層。 限制檔案附件元件上的檔案型別和大小、使用驗證器掃描提交內容，以及新增機器人保護（例如CAPTCHA）。 沒有單一圖層本身就足夠了。

寫入清除拒絕訊息。 結果中的message會向使用者顯示，因此使其可操作，例如「不允許此檔案型別」。 上傳PDF。」 如果您的表單提供多種語言，請考慮本地化。

安全並監視掃描通道。 使用安全傳輸至您的掃描引擎，由於它位於提交路徑中，因此保持高可用性，並記錄掃描結果以進行稽核和疑難排解。

常見問題 faq

什麼是AEM Forms中的檔案附件驗證器？
這是伺服器端服務，您在AEM中註冊，可在提交時檢查透過Adaptive Form上傳的每個檔案，並告知AEM是否接受或拒絕檔案。您透過​ 檔案附件病毒掃描程式/驗證器 ​設定在表單上選取它。

AEM何時呼叫驗證器？
在提交時，在保留表單資料和附件之前。AEM會使用附件呼叫您的validateFileAttachment方法，並在結果無效時封鎖提交。

一旦附加檔案，驗證執行時間是否可早於提交時間？
可以，作為單獨的機制。在使用者提交之前，使用最適化Forms規則編輯器中的​ 叫用服務 ​作業來呼叫檔案欄位變更事件的掃描服務。這與本文所述的FileAttachmentValidator介面無關。它會改為呼叫表單資料模型(FDM)服務。請參閱規則編輯器中的啟動服務增強功能。

驗證程式是在瀏覽器中還是在伺服器上執行？
在伺服器上。無法藉由停用JavaScript或在瀏覽器中編輯頁面來略過檢查。

我可以使用此介面的任何防毒軟體嗎？
是。介面不依賴任何特定引擎。您的實作可以呼叫本機掃描精靈、商業防毒或資料遺失產品，或遠端掃描API，然後將結果對應至FileAttachmentValidationResult。

被拒絕的檔案是否儲存在AEM？
否。因為在保留檔案之前，會先從記憶體評估檔案，因此絕不會將拒絕的檔案寫入存放庫。

當檔案被拒絕時，該如何顯示自訂訊息？
在您建構FileAttachmentValidationResult時設定message值。AEM在拒絕檔案時向使用者顯示該訊息。

範例情境 example-scenarios

相關的文章 related-articles